MarkBind in the Project Workflow

User Guide → MarkBind in the Project Workflow

MarkBind in the Project Workflow

As MarkBind is especially optimized as a project documentation tool, it integrates well with the workflow of software projects.

Authoring Workflow

While most IDEs provide previews for Markdown files, unless your MarkBind files are using basic Markdown syntax only, you are recommended to launch a live preview and check the rendering of the page as you modify the source file.

GitHub Project Workflow

If you use GitHub for your project, you can deploy your site to GitHub pages easily. You can even set up Travis to automatically deploy your site to GitHub pages whenever a branch in your repo is updated.

If you are using GitHub Pull Requests as part of your workflow, you can set up Netlify to show a preview of the site generated from the MarkBind code in the PR.

Using MarkBind for Project Documentation

Here is an example workflow for using MarkBind for both developer documentation and user documentation in a GitHub project:

Suppose the main development of the project is done in the master branch while product releases are done using the release branch.

You can keep the user docs in a separate directory (say user-docs) and set up a MarkBind project in that folder. When there is a new release, you can deploy the user-docs site to GitHub Pages for users to read.

Similarly, you can keep the dev docs in a separate directory (say dev-docs) and set up Netlify to deploy the site when there is an update to the master branch; that way, developers can see the latest version of dev-docs via the Netlify site.

Converting existing project documentation/wiki

MarkBind supports the automatic conversion of an existing GitHub wiki or docs folder containing Markdown files.

A MarkBind conversion involves the following:

  • Adding a Home page: If your project already has a README.md or Home.md, the content will be copied over to index.md. Otherwise, a default home page will be added.
  • Adding an About Us page: If your project already has about.md, this will be used as the About page. Otherwise, a default About page will be added.
  • Adding a top navigation bar.
  • Adding a site navigation menu: If your project has a valid _Sidebar.md file, it will be used as the site navigation menu. Otherwise, the menu will be built from your project's directory structure and contain links to all addressable pages.
  • Adding a custom footer: If your project has a valid _Footer.md file, it will be used as the website footer. Otherwise, a default footer will be added.
Conversion might not work if your project files have existing Nunjucks syntax.

To convert your existing project, follow these steps:

  1. Navigate into the project directory.
  2. Run markbind init --convert to convert the project.
  3. You can now preview the website using markbind serve to view your newly converted MarkBind website.
You only need to run the conversion once. Once you have converted your project, you can proceed to edit it as a normal MarkBind project.

Deploying the Site

Redirecting to a Custom 404 Page