• HOME
  • USER GUIDE
  • SHOWCASE
  • ABOUT
  • Configuring the Site

    The site.json file root directory is used to configure various aspects of a MarkBind website.

    Here is a typical site.json file:

    {
      "baseUrl": "/myproduct",
      "faviconPath": "myfavicon.png",
      "titlePrefix": "FooBar Dev Docs",
      "theme": "bootswatch-cerulean",
      "pages": [
        {
          "src": "index.md",
          "title": "Hello World",
          "layout": "normal",
          "searchable": "no",
          "externalScripts": [
            "https://cdn.plot.ly/plotly-latest.min.js"
          ],
          "frontmatter": {
            "header": "header.md"
          }
        },
        {
          "glob": "**/index.md"
        }
      ],
      "externalScripts": [
        "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"
      ],
      "deploy": {
        "message": "Site Update.",
        "repo": "https://github.com/myorg/myrepo.git",
        "branch": "gh-pages"
      },
      "globalOverride": {
        "footer": "my-footer.md"
      },
      "ignore": [
        "_site/*",
        "*.json",
        "*.md",
        "*.mbd",
        ".git/*"
      ],
      "plugins" : [
        "filterTags"
      ],
      "pluginsContext" : {
        "filterTags" : {
          "tags": ["tag1", "tag2"]
        }
      },
      "headingIndexingLevel": 4
    }
    

    baseUrl

    The base url relative to your domain. Default: ""(empty).

    If you are deploying to the site to GitHub pages, the baseUrl setting in the site.json should be set to the "/<repositoryName>" for the links in the deployed site to work correctly.
    Example: If you are using Github Pages to host your deployed website at repo myorg/myproduct (i.e., the website is published at https://myorg.github.io/myproduct), then your baseUrl should be "/myproduct".

    faviconPath

    The location of the favicon. Default: favicon.ico.

    If the favicon was recently changed, you may need to force-refresh the Browser to see the new image.

    titlePrefix

    The prefix for all page titles. The separator - will be inserted by MarkBind.

    theme

    (Optional) The theme for the generated site. Uses the default Bootstrap theme if not specified. See User Guide: Themes for more details.

    pages

    An array of pages to be rendered.

    • src/glob: src can be used to specify a file e.g., docs/index.md.
      Alternatively, glob can be used to define a file pattern in the glob syntax e.g., **/*.md.
    • title: The page <title> for the generated web page. Titles specified here take priority over titles specified in the front matter of individual pages.
    • layout: The layout to be used by the page. Default: default.
    • searchable: Specifies that the page(s) should be excluded from searching. Default: yes.
    • externalScripts: An array of external scripts to be referenced on the page. Scripts referenced will be run before the layout script.
    • frontMatter: Specifies properties to add to the front matter of a page or glob of pages. Overrides any existing properties if they have the same name, and overrides any front matter properties specified in globalOverride.

    Note: Page properties that are defined in site.json for a particular page will override those defined in the front matter of the page.

    Note: If multiple src (pages) or glob (globs) attributes match a file, MarkBind will merge properties from all entries. If there are conflicting properties, pages are given priority over globs. If there are multiple matching glob entries, the last entry is given priority.

    Example: Multiple entries matching index.md:

    {
      "pages": [
        {
          "src": "index.md",
          "title": "Hello World",
          "searchable": "no"
        },
        {
          "glob": "*.md",
          "layout": "normal",
          "searchable": "yes"
        }
      ],
    }
    

    The following properties will apply to index.md:

    {
      "src": "index.md",
      "title": "Hello World",  // Inherited from page
      "layout": "normal",      // Inherited from glob
      "searchable": "no",      // Page takes priority over glob
    }
    

    externalScripts

    An array of external scripts to be referenced on all pages. To reference an external script only on specific pages, externalScripts should be specified in pages instead. Scripts referenced will be run before the layout script.

    globalOverride

    Globally overrides properties in the front matter of all pages. Any property included in the global override will automatically be merged with the front matter of every single page, and override them if the property exists.

    ignore

    An array of file patterns to be ignored when copying files to the generated site. By default, MarkBind will copy all the files as assets of the generated site.

    The ignore pattern follows the glob pattern used in .gitignore. For example, *.md ignores all markdown source files.

    deploy

    The settings for auto-deployment to Github pages.

    • message [Optional. Default: "Site Update."]
      The commit message used for the deployment commit.

    • repo [Optional. Default: the current working project's repo]
      The repo you want to deploy to.
      Format: "https://github.com/<org|username>/<repo>.git" ("git@github.com:<org|username>/<repo>.git" if you use SSH)
      Example: "https://github.com/myorg/myrepo.git"

    • branch [Optional. Default: "gh-pages"]
      The branch that will be deployed to in the remote repo.

    plugins, pluginsContext

    A list of plugins to load. Plugins are user-defined extensions that can add custom features to MarkBind. pluginsContext contains settings to be applied to the loaded plugins. See User Guide: Using Plugins for more details.

    The example above uses tags as an example of configuring plugin settings, refer to the filterTags plugin for more details.

    headingIndexingLevel

    The level of headings to be indexed for searching. Default: 3 i.e., only headings of levels 1,2,3 will be indexed for searching.

    enableSearch

    Specifies that the website should use MarkBind's search functionality. Default: true. See User Guide: Making the Site Searchable for more details.