mkdocs
Make github pages hosted page of this readme file?
I feel like it could be beneficial to setup a workflow that would automatically publish the readme file as a MkDocs-based site on GitHub. The main benefit I could see here is the fact of a (probably) better search to find plugins, extensions, themes, etc. in it, which with current options (GitHub's repo search or simple Ctrl+F) is not as optimal I would say.
Tho, this is by no means something that has to be done here... Just an idea that could be considered.
True, it's especially not ideal that many projects are initially collapsed in a way that not even Ctrl+F would work.
But for a search setup, (other than the above caveat) I have a lot more trust in Ctrl+F than MkDocs' search. What kind of setup would it be?
What do you mean exactly with setup? The way to publish the site?
I think adding another job to the current update-best-of-list.yml file could be the best option here. Since it would be a single page that would use a pre-existing theme of MkDocs could the job be relatively straight forward:
jobs:
update-best-of-list:
# ... The action stuff already used
update-site:
needs: [update-best-of-list] # Make sure it runs after the file was updated
runs-on: ubuntu-latest
steps:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: 3.x
- name: Install MkDocs
run: python -m pip install mkdocs
- name: Generate mkdocs.yml file
run: echo "site_name: MkDocs Catalog" >> mkdocs.yml
- name: Move and rename README.md file
run: mv README.md docs/index.md
- name: Build docs
run: mkdocs build
- name: Configure GitHub Pages
uses: actions/configure-pages@v4
- name: Upload pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: site/
- name: Deploy to GitHub Pages
uses: actions/deploy-pages@v4
This should be enough to build and deploy the page whenever the README itself is being updated. Since MkDocs only needs the site_name to be defined in the config and defaults to including files from the docs dir should this be fairly straight forward...
Speaking of, I noticed that the docs mention the site_url to also be required, which can't be true as mkdocs new only generates a mkdocs.yml file containing the site_name option. I'll make a PR correcting this mistake in the docs, unless this is a future change that has been published to production docs by accident.
I'm going to close this for now, it's unclear how/if we want to integrate the catalog or just a gallery of themes within the official docs. All projects are now shown (no hidden projects that you have to expand), so Ctrl-F should work fine.
