Managing Your GitHub Pages

In nvim-best-practices-plugin-template, you have the option to automatically publish your work as HTML to a website (either hosted by GitHub or as a custom URL).

For example, this plugin can be viewed at https://colinkennedy.github.io/nvim-best-practices-plugin-template.

Enable GitHub Pages

Creating a website using GitHub is not on by default, you need to turn it on. To do that, first create a gh-pages branch. Either from the terminal or through Github

git checkout -b gh-pages

Note

The contents of the gh-pages branch doesn't matter because we're going to override it anyway. We just need gh-pages to exist, that's all

Next, enable GitHub pages and tell it to point to gh-pages. You can learn how to do it from GitHub's documentation or keep reading.

Navigate to the pages as follows:

Click the "Pages" button at the bottom of "Code and automation"

Under "Build and deployment", under "Source", select Deploy from a branch. Under "Build and deployment", under "Branch", use the branch dropdown menu and select a publishing source. You'll know you did it right if you see this:

Managing Your GitHub Pages

There are 3 main styles of website management. Before you setup anything, you should know which your style.

• Style 1 - Fully automatic - "I don't want to manage this website, just make it for me"
• Style 2 - Full-manual - "I want full control over every page of this website"
• Style 3 - Partially automatic - "I want some / most of the pages to be automatically generated. Let me manually write the rest"

Style 3 tends to be the best. You can make pretty, crafted landed pages and documentation. But you also still get all of your API automatically updated for you.

Setup

Style 1 - Fully automatic

If all you want is a website with basic links, you're already done. nvim-best-practices-plugin-template will do the rest for you.

Style 2 - Full manual

nvim-best-practices-plugin-template uses mkdocs to convert markdown into HTML files and is recommended. But really you can use any documentation generator as long as 1. It outputs .html 2. You output to the {root}/markdown/ folder of this repository.

And lastly you'll want to edit the documentation.yml file. Strip out all of the parts related to emmylua_doc_cli.

Click here to see a simplified documentation.yml

  # ... other jobs / stuff ...

  html_documentation:
    name: HTML Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Deploy To GitHub Pages
        uses: mhausenblas/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG_FILE: markdown/mkdocs.yml

Style 3 - Partially Automatic

To summarize what we're about to do - you manually generate the automated documentation from "Style 1" but then edit it and commit it to your liking. It's simple:

git checkout main
cargo install emmylua_doc_cli
emmylua_doc_cli --input lua/ --output markdown
# Remove the auto-generated portions
rm -rf markdown/docs/modules
rm -rf markdown/docs/types

Whatever is left is yours to edit and do what you want with. (If done correctly you should be left with a mkdocs.yml + index.md file.

git add markdown
git commit -m "Added hand-written files"
git push

The files you deleted earlier will be auto-created as a part of the generating your HTML website later. You don't need to commit any of those files if you don't want to.

How It Works

In short, we leverage third-party tools to convert lua -> markdown (using emmylua_doc_cli) -> html (using mkdocs).

Check out documentation.yml to see the basic implementation.