Skip to content

Quick Start

Go to your repository settings and turn on GitHub Pages on the branch gh-pages.

Turn on GitHub Pages

Copy the mkdocs.yml file to your repository:

See contents
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
site_name: mdsplit
site_url: https://alandefreitas.github.io/mdsplit/
repo_url: https://github.com/alandefreitas/mdsplit
repo_name: alandefreitas/mdsplit

site_description: Generate documentation from bulky README.md files

theme:
  name: material
  palette:
    scheme: preference
  features:
    - navigation.instant
    - navigation.sections
    - toc.integrate
    - header.autohide
  icon:
    repo: fontawesome/brands/git-alt

edit_uri: ""

plugins:
  - search
  - awesome-pages # https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin

google_analytics:
  - G-3H1KP9L0TN
  - auto

copyright: Copyright © 2020 Alan Freitas

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      use_pygments: true
      linenums: true
      linenums_style: pymdownx.inline
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.snippets
  - pymdownx.arithmatex:
      generic: true
  - meta

extra_javascript:
  - javascripts/config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

Copy the .github/workflows/docs.yml file to your repository:

See contents
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
name: Docs Generator

on:
  push:
    paths:
      - 'README.md'
      - '.github/workflows/docs.yml'

jobs:
  generateDOC:
    name: Docs Generator
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # Use this action workflow to update your README.md with the table of contents
      - uses: technote-space/toc-generator@v2
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MAX_HEADER_LEVEL: 3
          FOLDING: true
      # Use this step to use the latest version of mdsplit
      # Comment this step if you want the latest release
      - name: Download and build mdsplit from source
        run: |
          mkdir build
          cd build
          cmake .. -DCMAKE_C_COMPILER=/usr/bin/gcc-8 -DCMAKE_CXX_COMPILER=/usr/bin/g++-8  -DCMAKE_CXX_FLAGS="-O2" -DCMAKE_BUILD_TYPE=Release
          cmake --build . -j 2 --config Release
          sudo cmake --install .
          cd ..
      # Uncomment these steps to use the latest release of mdsplit
      #      - name: Download mdsplit
      #        uses: carlosperate/download-file-action@v1.0.3
      #        id: download-mdsplit
      #        with:
      #          file-url: 'https://github.com/alandefreitas/mdsplit/releases/download/v0.1.0/Executable.Linux.zip'
      #          file-name: 'mdsplit.zip'
      #          location: '.'
      #      - name: Unzip mdsplit
      #        run: |
      #          unzip mdsplit.zip
      #          rm -f mdsplit.zip
      #          sudo chmod +x mdsplit
      #          ls
      # Run mdsplit to generate docs
      - name: Generate Docs
        run: |
          mdsplit -r alandefreitas/mdsplit
      # Set up Python
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - name: Install mkdocs
        run: pip install mkdocs-material
      # https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
      - name: Install Navigation Plugin
        run: pip install mkdocs-awesome-pages-plugin
      # Deploy the mkdocs to the gh-pages branch
      - name: Deploy mkdocs
        run: mkdocs gh-deploy --force

In a few seconds, your README.md file will become a beautiful documentation.