Skip to content

Github Actions

You can integrate mdsplit with GitHub actions to regenerate the documentation whenever you change your README.md file.

Use this workflow to get started:

 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

Replace the settings with your repository information.

Most steps in this workflow are optional:

  • The step technote-space/toc-generator@v2 creates a table of contents for your README.md file
  • The second step downloads and builds the master version of mdsplit. This is the version we use in this repository, but you probably want to use a more stable version in your own repository. To do that, comment this step and use the third and forth steps instead.
  • The third and fourth steps (commented out) download the latest release version of mdsplit. That's probably what you want for your repository. Uncomment these steps to do that.
  • The next steps are pushing the docs to your master branch. Make any adjustments you might need.
  • The last steps are taking the docs from your master branch and publishing them to your gh-pages branch.