to support diagrams in markdown documents, add atom package:
"Markdown Preview Enhanced"
use mkdocs to generate documentation site using markdown.
mkdocs setup
references:
https://www.mkdocs.org/
https://www.mkdocs.org/user-guide/configuration/
https://github.com/mkdocs/mkdocs/
https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/diagrams.md
use mkdocs pymdown-extensions with superfences and custom fences to
support diagrams in mkdocs.
https://facelessuser.github.io/pymdown-extensions/
https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
https://mermaidjs.github.io/#/
https://github.com/squidfunk/mkdocs-material/issues/693
https://cdnjs.com/
https://github.com/mermaid-js/mermaid/
mkdir -p ~/Work/dapp/dms3 mkdir -p ~/Work/dapp/dms3/mkdocs-docs cd ~/Work/dapp/dms3
#Note: mermaid was removed after the mkdocs documentation was functional #initially the docs folder was setup as ~/Work/dapp/dms3/mkdocs-docs, #but later moved to ~/Work/dapp/dms3-docs
#Note: use clone of repo mermaid - cdnjs version has bad css that when a
style is added to flowchart svg, the page is disabled.
to build mermaid locally after cloning repo:
git clone https://github.com/mermaid-js/mermaid.git cd mermaid/ nvm list nvm use stable npm install webpack npm install yarn npm run build npm run release ls -alg dist/ cp -v dist/mermaid.min.js* ../mkdocs-docs/docs/js/ cp -v dist/mermaid.js* ../mkdocs-docs/docs/js/
cd ../ python --version pip --version sudo apt-get install pip
wget https://bootstrap.pypa.io/get-pip.py sudo python get-pip.py
sudo pip install mkdocs mkdocs --version mkdocs new mkdocs-docs cd mkdocs-docs mkdocs serve sudo pip install pymdown-extensions sudo pip install mkdocs-rtd-dropdown
to support math rendering:
https://stackoverflow.com/questions/27882261/mkdocs-and-mathjax/31926644
https://squidfunk.github.io/mkdocs-material/extensions/pymdown/
https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
roboto-slab fonts were downloaded from:
Free download fonts at http://sharefonts.net
unzip and move missing fonts into mkdocs-docs/docs/fonts/
usage
cd ~/Work/dapp/dms3-docs
build
mkdocs build
local live reload server
mkdocs serve # defaults to 127.0.0.1:8000 mkdocs serve --dev-addr=192.168.0.7:8000