npm i -g @codedoc/cli
CODEDOC is an open-source tool that helps you with creating beautiful and modern software documentation. It creates a JAMStack app from your markdown files that you can easily deploy on services such as GitHub Pages. Read the docs for more info.
npm i -g @codedoc/cli cd my-project codedoc init
Modify your markdown files (by default in
docs/md/, for example
docs/md/index.md) and see changes in real time. When you are done, build your documentations for deployment:
and if you are for example using GitHub Pages, deploy by pushing:
git add -A git commit -m "added docs" git push
While there are multiple frameworks and tools that help with building websites from a bunch of markdown files, I will only focus on those who are specifically designed for writing documentation/wikis, since the rest naturally come with a configuration overhead. You can read this section for more info on CODEDOC's features compared to the works mentioned here.
A lot of the ideas of the workflow are shared between Jekyll and CODEDOC. The reason I created CODEDOC despite Jekyll being out there because:
- Jekyll is a bit old-school and hence heavy handed by modern frontend standards (no component structure, etc),
- Jekyll's themes are not up to modern standards, and it is quite some work to create new themes,
- Jekyll is not yet specifically designed for documentation and project wikis (thats why GitHub has a separate wiki section for projects despite supporting Jekyll out of the box).
GitBook is a nice SaaS built specifically for documentation and project wikis. However:
- It lacks some essential features (such as code-snippet hints),
- It hides some essential features behind a paywall (for example the dark mode), which hurts open-source projects,
- It is not customizable enough for my taste.
The following tools and open-source libraries are used by CODEDOC, so shout-out to their creators/maintainers/collaborators:
Used for syntax highlighting in code snippets.
For picking the default colors (also thanks to Niyousha Karimi for helping on that front, besides helping with usability testing).
Used for the local development server.
Used for convenient copy-to-clipboard functionality.
Used for rendering LaTeX formulas.
Used for automatic color deduction/manipulation.