devcontainers-contrib / features

🐳 Extra add-in features for Devcontainers and GitHub Codespaces
MIT License
244 stars 128 forks source link

GitHub Pages for docs instead of src/*/README.md #298

Closed jcbhmr closed 1 year ago

jcbhmr commented 1 year ago

This is an actionable item from the #290 discussion.

Here's how it might happen:

  1. Create a docs/ folder
  2. Add some PHP server-side pages to the pages/ folder. Specifically:
    • An index home page for a list of all the features
    • A page for each feature that includes a generated OPTIONS table and other boilerplate
  3. Use wget to mirror the localhost:8080 dev served PHP into static HTML tree
  4. A GitHub Action to deploy the stuff to GitHub Pages
  5. @danielbraun89 enables GitHub Pages in the settings menu of this repo
  6. Profit!

Note that you can use literally any framework you want. Next.js, React, Vue, Django, doesn't matter. As long as you can either: 1) statically generate a site natively or 2) use wget or httrack or any other HTTP crawler to download the dynamic HTML and save it as .html files

I think we SHOULD keep the README.md for custom feature-specific details like this example README.md for the ACT feature:

> Run your GitHub Actions locally 🚀

You can find more information about Act on the [nektos/act] GitHub page.

This feature installs the `act` binary to `/usr/local/bin/act` by downloading it
from the [nektos/act] GitHub Releases page. You can set a specific version using
the `version` option in your `devcontainer.json` file. The version you specificy
**must be a valid Git tag** that corresponds to a GitHub Release.

[nektos/act]: https://github.com/nektos/act#readme

Here's another example a possible README.md for the DENO feature

> A modern runtime for JavaScript and TypeScript. \
> The easiest, most secure JavaScript runtime.

Details about how to use JavaScript functions provided by Deno is included in the
[Deno Runtime API] docs website. Information on using the CLI is included in
the [Deno manual].

This devcontainer feature is a fork of the [`deno_install`] project. It provides
the heavy lifting of determining which system-specific binary to download, we just
add it to the `$PATH`.

[deno runtime api]: https://deno.land/api
[deno manual]: https://deno.land/manual/getting_started/command_line_interface
[`deno_install`]: https://github.com/denoland/deno_install#readme

Note how these README.md files are sorta like the NOTES.md file that the devcontainer/action uses to make PRs? That's the gist that I was going for.

Why this is good

  1. It reduces the PR spam of this repo
  2. It makes the docs indexable by Google
  3. It lets us reliably change the template that generates the docs (to include our own branding, links, Gitter link, issue link, etc.)

See #290 for more details about how this might relate to other changes

jcbhmr commented 1 year ago

This doesn't seem likely to happen. Closing.