MarkBind in the Project Workflow
As MarkBind is especially optimized as a project documentation tool, it integrates well with the workflow of software projects.
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.
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.
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
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.
MarkBind supports the automatic conversion of an existing GitHub wiki or
docs folder containing Markdown files.
A MarkBind conversion involves the following:
Home.md, the content will be copied over to
index.md. Otherwise, a default home page will be added.
about.md, this will be used as the About page. Otherwise, a default About page will be added.
_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.
_Footer.md file, it will be used as the website footer. Otherwise, a default footer will be added.
To convert your existing project, follow these steps:
markbind init --convert to convert the project.
markbind serve to view your newly converted MarkBind website.