Adding Pages

User Guide → Adding Pages

Adding Pages

It is easy to add files to a MarkBind site as any file inside the becomes a part of the generated website.

This includes any static assets such as images and other media files.

Example If you have an image images/logo.png in your root directory, it will be available as <website-url>/images/logo.png in the generated website.

Example If you have a file tutorial/code.txt in your root directory, it will be available as <website-url>/tutorial/code.txt in the generated website.

You can specify which files to be omitted from the site by using the ignore field in the site.config file as explained here.

More importantly, .md files can be transformed into HTML pages with matching names.

Example <root>/tutorial/setup.md can be transformed into <website-url>/tutorial/setup.html

Here are the steps to add a new page to your site:

  1. Add a .md file anywhere inside the root directory.
  2. Update the pages attribute of the site.json to cover the new file, if necessary.
  3. Use the live preview to view the generated web page for the new file.

External Static HTML Web Pages

You can easily include and deploy any external , along with your MarkBind site.

Example Your code coverage tool generates a HTML Coverage Report into a coverage folder and you want it to be accessible at <website-url>/coverage/index.html

The general approach is as follows:

  1. Create a folder with the path that you want the HTML web page to be available at.
  2. Exclude the files from being further processed by MarkBind by adding them to the pagesExclude attribute of the site.json file.
  3. Generate the HTML files and put them in that folder (This can be done automatically by your build tool, either locally, or as part of your continuous integration process).
  4. Run markbind build to generate your MarkBind site.
  5. Deploy the built files manually or using a continuous integration process.

In the event that you only generate the static webpages in your CI build process, you may receive an invalid intra-link warning if you serve the MarkBind site locally. To disable it on a per-link basis, add {no-validation} at the end like this:

This is [my cool page generated from another tool](/my-cool-page/index.html{no-validation})

See the link Validation section for more details.

Generating Custom File Types

You can also use MarkBind to generate non-HTML files, such as .json or .txt, from your source .md files. This is useful for generating dynamic configuration files or other text-based assets that can benefit from MarkBind's variable system.

To do this, specify the fileExtension property for the page configuration in your site.json, as explained here.

Example Generating a sampleJson.json from sampleJson.md:

site.json:

{
  "pages": [
    {
      "src": "userGuide/customFileTypes/sampleJson.md",
      "fileExtension": ".json",
      "searchable": "no"
    }
  ]
}

sampleJson.md:

{
    "title": "globalVariables",
    "description": "This file is served as a .json file, but is sourced from a .md file in the source code.",
    "baseUrl": "{{baseUrl}}",
    "timestamp": "{{timestamp}}",
    "MarkBind": "{{MarkBind}}"
}

Examples of generated custom files:

  • sampleJson - A JSON file generated from Markdown, utilizing default global nunjucks variables available in MarkBind sites.
  • sampleTxt - A plain text file generated from Markdown, also utilizing global variables.

Key Points:

  • Nunjucks Variables: You can use Nunjucks global variables (like baseUrl, timestamp) and site variables within these files, just like in your HTML pages.
  • No Frontmatter or Scripts: Unlike standard MarkBind pages, custom file types do not support frontmatter or scripts. Frontmatter and script tags will be treated as plain text if included.
  • Search: By default, these files are searchable if enableSearch is true for the site. You can disable this by setting "searchable": "no" (or false) in the page config.
  • Intra-site validation: If you are linking such files in other pages in your site, you can use the {no-validation} tag, e.g. [sampleTxt](/userGuide/customFileTypes/sampleTxt.txt){no-validation} to disable intra-site validation warnings for the link, as MarkBind currently does not support intra-site validation for custom file type links.

Authoring Contents

MarkBind Syntax Overview