Docsify

• Website and Docs
• How to Write Good Documentation with Docsify
• Features:
  • Docsify renders Markdown documentation in the browser using JS, no need to generate html files from Markdown

  • Auto-generation of sidebar content with docsify generate

• Downside:
  • Docsify does not generate dynamic SEO meta tags for a page. It only generates a title and description
    • Generate static HTML site not planned
  • Not usable offline without adding components as assets to the repo

Install:

npm i docsify-cli -g

Initialize:

docsify init ./docs

Serve content with docsify:

docsify serve docs

Serve with nginx:

docker run -v $(pwd)/docs:/usr/share/nginx/html:ro --rm -p 8080:80 docker.io/nginx            │

Plugins

• List of Plugins
• Sidebar collapse:
  • mbertogliati/docsify-sidebar-collapse
    • CDN URLs for js and css files are blocked in browser

      The resource from https://unpkg.com/docsify-sidebar-collapse@1.3.5/dist/sidebar-collapse.min.css was blocked due to MIME type (“text/plain”) mismatch (X-Content-Type-Options: nosniff)

    • npm instructions are incomplete, can't find needed sidebar-collapse.min.css in dist/ dir
  • iPeng6/docsify-sidebar-collapse
    • Last commit 2021
• TOC
  • Upstream FR: Dedicated Sticky TOC (Table of Contents) on Right Side was closed
  • justintien/docsify-plugin-toc
    • Generate a TOC on top of the document
    • Last commit 2023
  • mrpotatoes/docsify-toc
    • Archived 2023
  • lyingdragon/docsify-plugin-page-toc
    • Generates a collapsible box at the right side
    • Last commit 2020

3rd party resources

• docsify_sidebar_generator.py
  • Auto-generates a sidebar based on all Markdown files
  • Could be added as a pre-commit hook