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 Forms.md CLI tool converts your Markdown form templates into static HTML pages, perfect for hosting on any web server or static hosting platform.

​
Installation

Install Forms.md globally via npm: 
npm install -g formsmd
Or use it with npx without installing: 
px formsmd --input src --output site

​
Quick start

1

Create your forms

Create Markdown files in a source directory:
mkdir src
echo "# Contact Form" > src/contact.md
2

Run the CLI

Generate your static site:
formsmd --input src --output site
3

Deploy

Upload the site directory to any web host or serve it locally:
cd site
python -m http.server 8000

​
Command options

The CLI accepts three command-line options:

​
Input directory

Specifies where your Markdown form templates are located. 
formsmd --input src
formsmd -i forms
Default: src

​
Output directory

Specifies where the generated HTML files will be saved. 
formsmd --output site
formsmd -o build
Default: site

​
Static directory name

Specifies the name of your static assets folder (images, CSS, etc.). 
formsmd --static-dir-name assets
formsmd -s public
Default: static
The static directory is automatically copied from input to output, preserving the folder structure.

​
Complete command

formsmd --input forms --output dist --static-dir-name assets
Short form: 
formsmd -i forms -o dist -s assets

​
Directory structure

​
Input structure

src/
├── contact.md
├── survey.md
├── application.md
├── base.html (optional)
└── static/
    ├── images/
    │   ├── logo.svg
    │   └── hero.jpg
    └── styles/
        └── custom.css

​
Output structure

After running the CLI: 
site/
├── contact.html
├── survey.html
├── application.html
├── content/
│   ├── contact.md.js
│   ├── survey.md.js
│   └── application.md.js
├── formsmd/
│   ├── css/
│   │   ├── formsmd.css
│   │   ├── formsmd.min.css
│   │   └── formsmd.rtl.css
│   └── js/
│       ├── formsmd.bundle.min.js
│       └── composer.bundle.min.js
└── static/
    ├── images/
    └── styles/
The CLI automatically includes all necessary Forms.md CSS and JavaScript files in the formsmd directory.

​
Creating forms

​
Basic form template

Create a Markdown file in your input directory: 
#! title = Contact Form
#! accent = #6366f1
#! post-url = https://example.com/api/contact

# Get in Touch

We'd love to hear from you!

name* = TextInput(
  | question = What is your name?
)

email* = EmailInput(
  | question = What is your email address?
)

message* = TextInput(
  | question = Your message
  | multiline
)

​
URL slugification

The CLI automatically creates URL-friendly filenames:
Markdown fileGenerated HTMLURL
contact.mdcontact.html/contact.html
About Us.mdabout-us.html/about-us.html
FAQ 2024.mdfaq-2024.html/faq-2024.html
Filenames are slugified using lowercase letters, hyphens, and strict mode (removes special characters).

​
Custom base template

Override the default HTML template by creating a base.html file in your input directory.

​
Default base template

The CLI includes a base template with this structure: 
<!DOCTYPE html>
<html lang="en" dir="{{ settings.dir }}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ settings.title }}</title>
  <link rel="stylesheet" href="/formsmd/css/formsmd.min.css">
</head>
<body>
  <div id="form"></div>
  <script type="module">
    import {{ route }}Template from '/content/{{ route }}.md.js';
    import { Formsmd } from '/formsmd/js/formsmd.bundle.min.js';
    
    const form = new Formsmd(
      {{ route }}Template,
      document.getElementById('form'),
      { isFullPage: true }
    );
    form.init();
  </script>
</body>
</html>

​
Custom template variables

Your custom base.html can use these Nunjucks variables:
VariableDescriptionExample
{{ route }}URL-friendly page namecontact
{{ settings.title }}Page title from #! titleContact Form
{{ settings.dir }}Text directionltr or rtl
{{ settings.* }}Any setting from your template{{ settings.accent }}

​
Example custom template

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ settings.title }} - My Company</title>
  <link rel="stylesheet" href="/formsmd/css/formsmd.min.css">
  <link rel="stylesheet" href="/static/styles/custom.css">
  <link rel="icon" href="/static/images/favicon.ico">
</head>
<body>
  <nav>
    <a href="/">Home</a>
    <a href="/contact.html">Contact</a>
    <a href="/survey.html">Survey</a>
  </nav>
  
  <div id="form-container"></div>
  
  <footer>
    <p>&copy; 2024 My Company</p>
  </footer>
  
  <script type="module">
    import {{ route }}Template from '/content/{{ route }}.md.js';
    import { Formsmd } from '/formsmd/js/formsmd.bundle.min.js';
    
    const form = new Formsmd(
      {{ route }}Template,
      document.getElementById('form-container'),
      {
        isFullPage: false,
        paddingInlineTop: 40,
        paddingInlineBottom: 40
      }
    );
    form.init();
  </script>
</body>
</html>

​
Static assets

The CLI automatically copies your static assets directory.

​
Organizing assets

src/
├── contact.md
└── static/
    ├── images/
    │   ├── logo.svg
    │   ├── hero.jpg
    │   └── favicon.ico
    ├── styles/
    │   └── custom.css
    ├── scripts/
    │   └── analytics.js
    └── fonts/
        └── custom-font.woff2

​
Using assets in forms

#! background-image = url('/static/images/hero.jpg')
#! brand = ![Logo](/static/images/logo.svg)
#! favicon = /static/images/favicon.ico
Use absolute paths starting with /static/ to reference your assets.

​
RTL support

The CLI automatically includes RTL stylesheets: 
#! localization = ar
#! dir = rtl
This loads formsmd.rtl.css instead of the standard stylesheet.

​
Development workflow

Use a file watcher to rebuild on changes:
npm install -g nodemon
nodemon --watch src --ext md,html --exec "formsmd -i src -o site"

​
Deployment

Deploy your generated site to any static hosting platform: 
# Install Netlify CLI
npm install -g netlify-cli

# Build and deploy
formsmd -i src -o site
netlify deploy --prod --dir=site

​
Build optimization

The CLI automatically optimizes the output:
  • Minified CSS (formsmd.min.css)
  • Minified JavaScript bundles
  • Escaped backticks in templates
  • Slugified URLs
  • Organized file structure
  1. Compress images before placing in static/
  2. Enable gzip on your web server
  3. Set cache headers for static assets
  4. Use a CDN for the formsmd directory
  5. Lazy load images in your forms

​
Multiple forms example

Manage multiple forms in one project: 
formsmd -i forms -o public

forms/
├── contact.md
├── newsletter.md
├── job-application.md
├── customer-survey.md
└── static/
    └── images/
Generates: 
public/
├── contact.html
├── newsletter.html
├── job-application.html
├── customer-survey.html
└── ...

​
Troubleshooting

If formsmd command is not found:
# Check if globally installed
npm list -g formsmd

# Reinstall globally
npm install -g formsmd

# Or use npx
npx formsmd -i src -o site
The CLI creates the output directory automatically. If it fails:
# Check write permissions
ls -la

# Manually create directory
mkdir site

# Run CLI again
formsmd -i src -o site
Ensure your static directory name matches the CLI flag:
# If your folder is named 'assets'
formsmd -i src -o site -s assets

# Check directory structure
tree src
  1. Check browser console for errors
  2. Verify JavaScript files loaded correctly
  3. Ensure forms.md library is included
  4. Check for syntax errors in Markdown templates

​
Next steps

Form inputs

Learn about all available input types

Google Sheets

Save responses to Google Sheets