docs: add documentation website and trim readme - #160
Merged
Conversation
All guidance lived in a single README that had drifted from the repository and buried the configuration details under two large CI generated quarto check transcripts. Add a Quarto website under docs/ using the atelier project type, with a midnight and amber brand, the gitlink navbar widget, and iconify icons on the navbar and sidebar entries. Cover getting started with Codespaces, Dev Containers and the template, and reference every configuration, image tag, Dev Container feature and init-env.sh option. The atelier project type contributes its own theme, which a project level theme replaces rather than extends, so the extension stylesheet is listed explicitly before the project layer.
Move the injected transcripts from README.md to docs/reference/quarto-check.qmd, so the README stays short and the output is rendered with the rest of the reference material. quarto check redraws its progress spinner with carriage returns, which Pandoc reads as line breaks; left in place they broke the enclosing div and truncated the page, so strip them and surround the injected block with blank lines. Read the transcript from the file inside awk rather than passing it as a multi-line -v value, which is not portable across awk variants and made local dry runs impossible.
Point at the documentation website and keep only the badges, the two Codespaces entry points, the image tag table and the Dev Container snippet. Fix the two links to init.sh, which is named init-env.sh, and drop the stale Codespaces menu wording and the unverified base image version claim for the universal configuration.
mcanouil
added
Type: Documentation 📝
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Quarto website under
docs/, built with theatelierproject type and a midnight and amber_brand.yml, published to GitHub Pages at https://m.canouil.dev/quarto-codespaces. The navbar carries thegitlinkrepository widget, and navbar and sidebar entries carry Octicons throughiconify.The site covers getting started with Codespaces, local Dev Containers and the template, and documents every
.devcontainerconfiguration, the image tag scheme and architectures, the six local Dev Container features, and everyinit-env.shoption.The
quarto checktranscripts move fromREADME.mdtodocs/reference/quarto-check.qmd, and theupdate-readmejob in the build workflow becomesupdate-docs, patching that page instead.quarto checkredraws its progress spinner with carriage returns, which Pandoc reads as line breaks; left in place they broke the enclosing div and truncated the page, so the injector now strips them and surrounds the injected block with blank lines. The transcript is also read from the file insideawkrather than passed as a multi-line-vvalue, which is not portable acrossawkvariants.A new
deploy.ymlrendersdocs/and deploys to GitHub Pages, authenticating through the GitHub App with the sharedsetup-git-useraction.README.mddrops to a landing page pointing at the site. It fixes the two links toinit.sh, which is namedinit-env.sh, and drops the stale Codespaces menu wording and the unverified base image version claim for the universal configuration.