Make github pages hosted page of this readme file?

[Andre601]

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.

[oprypin]

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?

[Andre601]

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.

[pawamoy]

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.