Developer Notebook for
Notes are online at
- Easier to write things down then trying to remember what you forgot.
- Working on web development projects is changing rapidly and constantly.
- Resources are available everywhere but some are outdated and only some help with solving your problem.
- Easier to review notes on how you solved it last time than googling and going through all the articles again.
- Too much Googling can lead to a waste of time.
- Track your development
Creating Project Documentation
- Notes are written in Markdown
- Using IA Writer and Microsoft Visual Studio Code to edit the docs.
- Site generated with MkDocs
- Deciding factor was the ability to push docs to gh-pages on Github.
- Essentially free hosting for my document notebook.
- Notes for setting up notebook in notebook.
- Uses markdown.
- Works with github pages.
- Every project will have their own documentation
- Styleguide should be included (frontend)
- Project goals and requirements
- Notes about development
- Setup/install instructions
- Resolution to issues (ongoing FAQ for the projects)
- Documentation pages stay in gh-pages branch.
- Create project directory and CD into it
- Install mkdocs as dev dependency -
pipenv install mkdocs --dev
- Create mkdocs direcotry -
mkdocs new sitedocs
- sitedocs\docs is where the markdown goes.
- sitedocs\mkdocs.yml - your table of contents.
mkdocs serve - local development server http://localhost:8000
mkdocs gh-deploy - build docs and push to gh-pages repo in github after committing.
Config file -
site_name: Development Notes for Johan Martin
site_description: Notes tracking for developing different apps.
site_author: Johan Martin (http://www.johan-martin.com)
# docs_dir: 'md'
# site_dir: 'docs'
copyright: Johan Martin © 2017
- Home: 'index.md'
- 'Page Sites': 'page.md'
- sub1: 'sub1.md'
- sub2: 'sub2.md'
Installing Markdown Extensions
Fixing Issues with MkDocs
pymdownx.tilde extension to get strikethrough to work.
mkdocs gh-deploy to upload docs.
- Additional setup notes
Importing docs into Github
- 404 error for home page/front page - github gh-pages hosting.: Seems like the home page has to point to an "index.md" page for it to work.
- RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult http://click.pocoo.org/python3/for mitigation steps.
- Fix with:
> export LC_ALL=en_US.UTF-8
> export LANG=en_US.UTF-8
- Already being used by MkDocs.
- Would like to use with Sphinx if I convert my documentation to Sphinx.
Monday 13 April 2020
- Updated notes about WordPress CLI
- 24 April 2018 - Added API section. PHP, Python, Node.js frameworks related creating APIs.
* Added notes about pipenv
- Refactor documents to simplify and make relevant.
- Web Development