Development Environment Steup

Project page generation

  • To make the project page, install mkdocs:
pip install mkdocs
  • Then install python-markdown-math
pip install python-markdown-math
  • To initialize the directory
mkdocs new .
  • To generate the documentation
mkdocs serve
  • To deploy to github
mkdocs gh-deploy

mkdocs reference

How to display math properly

  • I follow this instructions.
    • I need to create a docs/javascripts/mathjax.js
    • I also need to do the following in mkdocs.yml
    • About mathjax version: see here.
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  • If I just need to use 2.7.7, then I can simply do: 
extra_javascript: 
    - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS-MML_CHTML

VScode extensions

  • I use VScode as my IDE. To make typing equation easier in markdown file, the following 3 extensions have been installed:

  • With these 3 extensions, I can write equations easier, e.g.

    • Use ii to insert inline equations.
    • Use dd to insert display math.

  • Other user defined latex snippet are located under snippets/latex.json. It's better to create a global user snippet and copy over the contents to there: (control palette -> "Snippets" -> "New Global").

  • In addition, to make the intellisense work for markdown file, I need to edit the settings.json (control palette -> "open user settings") by adding the following lines.

    "[markdown]": {
        "editor.quickSuggestions": {
            "other": true,
            "comments": false,
            "strings": false
        }
    }
  • Furthurmore, I would like to use Tab key to cycle through the suggestions, so I need to edit the keybindings.json file (control palette -> "Preference: Open Keyboard Shortcuts (JSON)"). The reference is here.
{
        "key": "tab",
        "command": "selectNextSuggestion",
        "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
      },
      {
        "key": "down",
        "command": "-selectNextSuggestion",
        "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
      },
        {
        "key": "shift+tab",
        "command": "selectPrevSuggestion",
        "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
      },
      {
        "key": "up",
        "command": "-selectPrevSuggestion",
        "when": "suggestWidgetMultipleSuggestions && suggestWidgetVisible && textInputFocus"
      }

Similar Projects