How to use
Learn how to install and convert your Markdown files, override the base template, configure the initialization options, etc.
Install via npm
npm
Convert Markdown files to forms and pages
Once you've installed blocks.md, put all of your Markdown files in a src
directory. You can also have your images and media files in src/static
(that is, within the input directory), and this directory will be copied for you. Once you're ready, run the following command in your CLI:
By default, this command will look for a directory called src
and place the resulting output in a new site
directory. It will also create the necessary CSS and JS files in a new site/blocksmd
directory (that is, within the output directory) and copy the static files. However, you can specify the input and output directories, and also set the name of the static directory using the following options:
So for example, if you wanted to convert the Markdown files in the cms/pages
directory and place the output in website
, you would run the following:
The output folder is a static site with regular HTML files, and you can host them on Github Pages, Netlify, Vercel, etc. For example, you can literally drag and drop an output folder created using blocks.md to Netlify Drop, and your forms and pages will all work properly.
Routes and mapping
The filenames of the Markdown files become the routes because each input Markdown file is mapped to an output HTML file with the same name. For example, if you had index.md
and survey.md
in your input folder, your output folder would contain index.html
and survey.html
after running the blocksmd
command.
Pre-fill form fields using URL parameters
Let's say you had apply.md
in your input folder with a form field:
You could pre-fill this form field using a URL parameter, like so: https://example.com/apply?position=Engineer
. In this case, the Engineer
option would be selected by default. Multiple fields are also supported: https://example.com/apply?position=Engineer&option=1
.
Base template
The blocksmd
command looks for base.html
in your input folder and uses this as the base to create all of the output HTML files. If you don't have a base.html
file, it uses the built-in one that comes with the library. Therefore, if you want to change the base template for creating the output files, just have your version of base.html
in your input folder, so that you may choose to do the following:
Change the metadata tags.
Write your own CSS to style your forms and pages.
Include additional CSS and JS files. For example, you could include Tailwind CSS in your
base.html
, set#! css-prefix = none
, and start using Tailwind utility classes for some incredible looking pages and layouts.Change the initialization options.
And much more. The base template has access to the following data:
The settings, for example:
{{ settings["title"] }}
The route (filename of the input Markdown file), for example:
{{ route }}
blocks.md uses Nunjucks to handle the templating, so its entire list of features such as if-else statements, loops, filters, etc. are fully supported.
Initialization options
During initialization of each form/page, the blocksmd.init(...)
function is called. You can see this in base.html
. This function takes the template (as a string) as the first argument, and an object as the second argument. This object contains the options which are used in various parts of the workflow. These are called the initialization options. For example:
The following options are available to use during initialization:
getHeaders
getHeaders
Object containing headers to send with the GET request if you set up a #! get-url = {url}
. Learn more about setting and reading data.
Type: Object
Default:
{}
postData
postData
Extra data to send over with the form responses. Learn more about sending responses.
Type: Object
Default:
{}
postHeaders
postHeaders
Object containing headers to send with the POST request (for form responses). Learn more about sending responses.
Type: Object
Default:
{}
prioritizeURLFormData
prioritizeURLFormData
Whenever a user inputs some data in any of the form fields, that data is automatically saved in local storage. If the user leaves the form before completing it, the saved form data is pre-filled when the user returns back to the page.
As mentioned above, you can also pre-fill form fields using URL parameters, for example: https://example.com/apply?position=Engineer
.
By default, the data saved in local storage is given preference over the URL parameters, because the former comes from user's input. However, if for some reason, you want to always prioritize the URL parameters, set this option to true
.
Type: Boolean
Default:
false
sanitize
sanitize
If set to true
, the template will first be sanitized using DOMPurify.
Type: Boolean
Default:
false
setColorSchemeAttrsAgain
setColorSchemeAttrsAgain
By default, blocks.md will use the saved color scheme preference (light or dark mode) and set it during page load. It will set it again during the template initialization. You can stop the second instance by setting this option to false
.
This is slightly difficult to understand, but the practical explanation is that if you're using some other method of setting the saved color scheme preference (for example, cookie from the server side), you may need to set this to false
.
Type: Boolean
Default:
true
Last updated