Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/formsmd/formsmd/llms.txt

Use this file to discover all available pages before exploring further.

The formsmd CLI tool compiles your Markdown files into static HTML pages with Forms.md functionality.

​
Installation

Install Forms.md globally or as a dev dependency: 
npm install -g forms.md

​
Basic usage

formsmd --input src --output site
This command reads Markdown files from the src directory and generates HTML files in the site directory.

​
Command

​
formsmd

Compile Markdown files into Forms.md HTML pages. 
formsmd [options]

​
Options

​
--input
string
default:"src"
required
Aliases: -iSpecifies the input directory containing your Markdown files. The CLI will process all .md files in this directory.
formsmd --input src
formsmd -i pages
​
--output
string
default:"site"
required
Aliases: -oSpecifies the output directory where HTML files will be generated. The CLI creates this directory if it doesn’t exist.
formsmd --output dist
formsmd -o public
​
--static-dir-name
string
default:"static"
required
Aliases: -sName of the static directory for images, media files, and other assets. This directory is copied from the input directory to the output directory.
formsmd --static-dir-name assets
formsmd -s public

​
How it works

The formsmd CLI performs the following operations:
  1. Reads Markdown files - Scans the input directory for all .md files
  2. Parses settings - Extracts Forms.md settings from #! prefixed lines
  3. Generates routes - Creates URL-friendly routes based on file names (slugified)
  4. Compiles HTML - Renders each Markdown file into a complete HTML page
  5. Copies assets - Copies the Forms.md library files and your static directory to output

​
Output structure

For an input directory with this structure: 
src/
├── contact-form.md
├── survey.md
├── base.html (optional)
└── static/
    ├── logo.png
    └── background.jpg
The CLI generates: 
site/
├── contact-form.html
├── survey.html
├── content/
│   ├── contact-form.md.js
│   └── survey.md.js
├── formsmd/
│   ├── formsmd.css
│   └── formsmd.js
└── static/
    ├── logo.png
    └── background.jpg

​
File naming

The CLI converts Markdown file names to URL-friendly routes:
  • Converts to lowercase
  • Removes special characters
  • Replaces spaces with hyphens
  • Removes file extension

​
Examples

Input FileOutput Route
Contact Form.mdcontact-form.html
Customer_Survey.mdcustomer-survey.html
FAQ.mdfaq.html

​
Custom base template

You can provide a custom base.html file in your input directory to override the default template. The CLI uses this template for all generated pages.

​
Template variables

Your custom base.html can use these Nunjucks variables: 
<!DOCTYPE html>
<html>
<head>
  <title>{{ settings.title }}</title>
  <!-- Access any setting from the settings object -->
</head>
<body data-route="{{ route }}">
  <!-- Your page structure -->
</body>
</html>
​
route
string
The URL-friendly route name for the current page (without file extension).
​
settings
object
Object containing all page settings (both defaults and user-defined).Access any setting like {{ settings.title }}, {{ settings.accent }}, etc.

​
Usage examples

​
Basic build

formsmd --input src --output dist

​
Custom directories

formsmd -i content -o build -s assets

​
In package.json scripts

{
  "scripts": {
    "dev": "formsmd -i src -o dist && serve dist",
    "build": "formsmd -i src -o dist"
  }
}

​
With a build tool

{
  "scripts": {
    "build:forms": "formsmd -i src/forms -o dist",
    "build": "npm run build:forms && vite build"
  }
}

​
Working directory

The CLI runs from your current working directory. All paths are relative to where you execute the command. 
# Run from project root
formsmd -i src -o dist

# Run from a subdirectory (paths still relative to where you run it)
cd forms
formsmd -i . -o ../dist

​
Error handling

The CLI provides error messages for common issues:

​
Unable to read input directory

Unable to read input directory: ENOENT: no such file or directory
Solution: Verify the input directory exists and the path is correct.

​
Invalid Markdown syntax

If a Markdown file has syntax errors, the CLI logs the error and continues processing other files. 
Error processing file: survey.md
[Error details]

​
Integration examples

​
Next.js

{
  "scripts": {
    "build:forms": "formsmd -i content/forms -o public/forms",
    "build": "npm run build:forms && next build"
  }
}

​
Vite

{
  "scripts": {
    "dev": "concurrently \"vite\" \"formsmd -i forms -o dist --watch\"",
    "build": "formsmd -i forms -o dist && vite build"
  }
}
The CLI doesn’t include a watch mode. Use a tool like nodemon or concurrently for development workflows.

​
With nodemon for development

{
  "scripts": {
    "dev": "nodemon --watch src --ext md --exec 'formsmd -i src -o dist && serve dist'"
  },
  "devDependencies": {
    "nodemon": "^3.0.0",
    "serve": "^14.0.0"
  }
}

​
Best practices

  1. Version control - Add the output directory to .gitignore since it contains generated files 
    # .gitignore
dist/
site/
public/forms/
  2. Build scripts - Use npm scripts for consistent builds across environments
  3. Static assets - Keep all images and media in the static directory for proper copying
  4. File naming - Use descriptive, URL-friendly names for your Markdown files
  5. Custom templates - Store your base.html in version control for team consistency