diff --git a/docs/about/index.md b/docs/about/index.md index 67efd44..7a93cd6 100644 --- a/docs/about/index.md +++ b/docs/about/index.md @@ -1,5 +1,5 @@ --- -title: "About Anonymous Planet" +title: "Anonymous Planet" description: We are the maintainers of the Hitchhiker's Guide and the PSA Matrix space. schema: "@context": https://schema.org diff --git a/docs/changelog/index.md b/docs/changelog/index.md index 59bb44c..2a7e3ad 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -1,6 +1,6 @@ --- -title: "TBA" -description: "" +title: "Release Notes" +description: "Release Notes" schema: "@context": https://schema.org "@type": Organization @@ -14,55 +14,56 @@ schema: - https://mastodon.social/@anonymousplanet --- -# Changelog +# Release Notes All notable changes to this project will be documented in this file. ## [Unreleased] -### Added +!!! Note "Added" -- This changelog page -- Add ways to verify the files + - This changelog page + - Add ways to verify the files -### Changed +!!! Note "Changed" -- Refactored GitHub Actions workflow **Build PDF** (`scripts\build_guide_pdf.py`): now builds both light and dark mode PDFs (`export/thgtoa.pdf` and `export/thgtoa-dark.pdf` respectively). -- Restored previous VT scans + - Refactored GitHub Actions workflow **Build PDF** (`scripts\build_guide_pdf.py`): now builds both light and dark mode PDFs + - Restored previous VT scans -## Fixed +!!! Note "Fixed" -- `docs/about/index.md`: replace broken reference-style internal links -- `docs/guide/index.md`: Appendix A6: comment out deprecated ODT information because we don't and probably won't use it in the future + - `docs/about/index.md`: replace broken reference-style internal links + - `docs/guide/index.md`: Appendix A6: comment out deprecated ODT information because we don't and probably won't use it in the future -### Feature +!!! Note "Feature" -- Updated `scripts/build_guide_pdf.py` to use `--print-to-pdf` instead of `--save-as` for PDF generation, and added a new `--dark-mode` flag to generate dark mode PDFs. The script now supports generating both light and dark mode PDFs with a single command invocation by using the `--both` flag. This change improves the PDF generation process and provides better support for dark mode users. Save your eyes - you only get one pair. + - Updated `scripts/build_guide_pdf.py` to use `--print-to-pdf` instead of `--save-as` for PDF generation + - Added a new `--dark-mode` flag to generate dark mode PDFs. Save your eyes - you only get one pair. -## [1.2.1] - 2026-04-11 +## [v1.2.1] -### Added +!!! Note "Added" -- GitHub Actions workflow **Build PDF** (`.github/workflows/build-pdf.yml`): installs Chromium on `ubuntu-latest`, runs `scripts/build_guide_pdf.py`, uploads `export/guide.pdf` as the `guide-pdf` artifact. Runs on `workflow_dispatch`, on pushes to `main` that touch docs or build inputs, and on matching pull requests. + - GitHub Actions workflow **Build PDF** (`.github/workflows/build-pdf.yml`): installs Chromium on `ubuntu-latest`, runs `scripts/build_guide_pdf.py`, uploads `export/guide.pdf` as the `guide-pdf` artifact. Runs on `workflow_dispatch`, on pushes to `main` that touch docs or build inputs, and on matching pull requests. -- `scripts/build_guide_pdf.py` to build the MkDocs site and render the guide to a single PDF (`export/guide.pdf` by default) using a Chromium-based browser (Chrome or Edge) headless print-to-PDF. -- `docs/stylesheets/extra.css` and `extra_css` in `mkdocs.yml` for shared site styling. -- This `CHANGELOG.md`. + - `scripts/build_guide_pdf.py` to build the MkDocs site and render the guide to a single PDF (`export/guide.pdf` by default) using a Chromium-based browser (Chrome or Edge) headless print-to-PDF. + - `docs/stylesheets/extra.css` and `extra_css` in `mkdocs.yml` for shared site styling. + - This `CHANGELOG.md`. -### Changed +!!! Note "Changed" -- `README.md` “Ways to read or export the guide”: hosted link, local `mkdocs serve`, PDF build via the script, ODT note, raw Markdown link. -- Guide landing layout: wrap the opening block in `docs/guide/index.md` with a `guide-intro-lead` container so the logo and first sections share one layout context for web and print. -- `.gitignore` to exclude local build outputs `export/`, `site/`, and `_site_test/`. -- `scripts/build_guide_pdf.py`: when the `CI` environment variable is set, pass Chromium flags (`--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`) so headless print works on typical CI images. -- `README.md`: note the **Build PDF** GitHub Actions workflow and the `guide-pdf` artifact. + - `README.md` “Ways to read or export the guide”: hosted link, local `mkdocs serve`, PDF build via the script, ODT note, raw Markdown link. + - Guide landing layout: wrap the opening block in `docs/guide/index.md` with a `guide-intro-lead` container so the logo and first sections share one layout context for web and print. + - `.gitignore` to exclude local build outputs `export/`, `site/`, and `_site_test/`. + - `scripts/build_guide_pdf.py`: when the `CI` environment variable is set, pass Chromium flags (`--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`) so headless print works on typical CI images. + - `README.md`: note the **Build PDF** GitHub Actions workflow and the `guide-pdf` artifact. -### Fixed +!!! Note "Fixed" -- `docs/guide/index.md`: replace broken reference-style internal links (`[label][label:]`) with working same-page fragment links to the correct headings; correct the mismatched “Real-Name System” cross-reference; fix a broken footnote marker on the “free (unallocated) space of your hard drive” list item. + - `docs/guide/index.md`: replace broken reference-style internal links (`[label][label:]`) with working same-page fragment links to the correct headings; correct the mismatched “Real-Name System” cross-reference; fix a broken footnote marker on the “free (unallocated) space of your hard drive” list item. [Unreleased]: https://github.com/Anon-Planet/thgtoa/compare/v1.2.1...HEAD -[1.2.1]: https://github.com/Anon-Planet/thgtoa/releases/tag/v1.2.1 +[v1.2.1]: https://github.com/Anon-Planet/thgtoa/releases/tag/v1.2.1 ***The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),*** -***and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).*** +***and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).*** diff --git a/docs/guide/dev-workflow.md b/docs/guide/dev-workflow.md index 7aa38d4..c55a068 100644 --- a/docs/guide/dev-workflow.md +++ b/docs/guide/dev-workflow.md @@ -8,11 +8,11 @@ **VirusTotal Scanning:** - Automatically scans PDFs and updates release notes **Release Automation:** - Packages everything into GitHub releases -## Workflow Architecture +## Architecture ### Build PDF Workflow (`build-sign-release.yml`) -??? Note "Steps" +!!! Note "Steps" - Checkout repository - Set up Python and MkDocs Material @@ -34,7 +34,7 @@ **Purpose:** Verify authenticity and prevent tampering -??? Note "How it works" +!!! Note "How it works" - Detached signatures created for each PDF and hash file - Public keys available in `/pgp/` directory diff --git a/mkdocs.yml b/mkdocs.yml index 470c179..2afac81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,6 +17,8 @@ theme: text: Public Sans code: Liberation Mono features: + - navigation.instant + - navigation.instant.prefetch - navigation.tabs - navigation.sections - toc.integrate @@ -122,7 +124,7 @@ markdown_extensions: toc_depth: 3 nav: - - Home: index.md + - Welcome: index.md - About: about/index.md - Verify: verify/index.md - Guide: @@ -133,7 +135,7 @@ nav: - Constitution: constitution/index.md - Mirrors: mirrors/index.md - Twitter: twitter/index.md - - TBA: changelog/index.md + - Releases: changelog/index.md copyright: | © 2023-2026 Anonymous Planet diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index 4c9497b..0000000 --- a/scripts/README.md +++ /dev/null @@ -1,132 +0,0 @@ -# PDF Build, Scan & Release Scripts - -This directory contains scripts for building PDFs from MkDocs documentation, scanning them with VirusTotal, generating hashes, and uploading artifacts to GitHub releases. - -## Scripts - -### `pdf_release.sh` (v2 - Recommended) -The main script that handles: -- SHA256 hash generation for PDF files -- VirusTotal scanning of PDFs -- Release creation/update on GitHub -- GPG signature verification support - -**Usage:** -```bash -./scripts/pdf_release.sh --build --release [--vt-api-key VT_KEY] [--github-token TOKEN] -``` - -**Options:** -- `--build`: PDF build mode (`light`, `dark`, or `both`) - Required -- `--release`: Release update mode (`tag` for tagged releases, `latest` to always update) - Default: `tag` -- `--vt-api-key`: VirusTotal API key (optional) -- `--github-token`: GitHub token for release operations (optional) - -### `build_guide_pdf.py` -Python script that builds MkDocs documentation and converts it to PDF using Chromium/Chrome. - -**Usage:** -```bash -python scripts/build_guide_pdf.py --both # Build both light and dark mode -python scripts/build_guide_pdf.py --dark-mode # Dark mode only -python scripts/build_guide_pdf.py --skip-mkdocs # Skip MkDocs build, use existing site -``` - -## GitHub Actions Workflow - -The workflow `.github/workflows/build-pdf-combined.yml` combines all operations: - -1. **Build PDFs** - Generates light/dark mode PDFs with GPG signatures -2. **Scan & Release** - Scans with VirusTotal and updates/releases artifacts - -### Required Secrets - -Add these to your repository settings under **Settings > Secrets and variables > Actions**: - -- `GPG_PRIVATE_KEY`: Your GPG private key for signing -- `GPG_PASSPHRASE`: Passphrase for the GPG key (if any) -- `VT_API_KEY`: VirusTotal API key for malware scanning -- `GITHUB_TOKEN`: Automatically available, but can be manually added - -### Workflow Triggers - -The workflow runs on: -- Manual dispatch (`workflow_dispatch`) with customizable options -- Push to main branch when docs, mkdocs.yml, or scripts change - -## Output Files - -After running the build and release process, you'll get: - -``` -export/ -├── thgtoa.pdf # Light mode PDF -├── thgtoa-dark.pdf # Dark mode PDF -├── thgtoa.pdf.sig # GPG signature for light PDF -├── thgtoa-dark.pdf.sig # GPG signature for dark PDF -├── thgtoa.pdf.sha256 # SHA256 hash for light PDF -├── thgtoa-dark.pdf.sha256 # SHA256 hash for dark PDF -├── sha256sum-combined.txt # Combined hash file -├── sha256sum-combined.txt.sig # GPG signature for combined hashes -└── virus-total-results.md # VirusTotal scan results -``` - -## Hash Verification - -To verify the integrity of downloaded PDFs: - -```bash -# Verify against individual hash file -sha256sum -c thgtoa.pdf.sha256 - -# Or verify against combined hash file -sha256sum -c sha256sum-combined.txt -``` - -## VirusTotal Integration - -When a `VT_API_KEY` is provided, the script will: -1. Upload each PDF to VirusTotal's API -2. Generate individual scan reports -3. Include VT report links in release notes and artifacts - -The VT results file (`virus-total-results.md`) contains: -- Scan timestamp -- SHA256 hashes for each PDF -- Direct links to VirusTotal GUI reports - -## Release Management - -The script supports two release modes: - -1. **Tag mode** (`--release tag`): Updates the release matching the current git tag -2. **Latest mode** (`--release latest`): Always updates the most recent release (useful for continuous deployment) - -When running in a GitHub Actions workflow with a tag push, it will automatically create or update the corresponding release. - -## Troubleshooting - -### PDF Build Fails -- Ensure Chrome/Chromium is installed: `sudo apt install chromium-browser` -- Check MkDocs configuration is valid: `mkdocs build --strict` -- Verify all documentation files are present and properly formatted - -### VirusTotal Scan Fails -- Check VT_API_KEY secret is correctly set in repository settings -- Verify the API key has sufficient quota (free tier allows 4 requests/minute) -- Check network connectivity to VirusTotal API - -### Release Upload Fails -- Ensure GITHUB_TOKEN has appropriate permissions (repo scope) -- For existing releases, use `--release latest` instead of `tag` -- Check that the release tag format matches GitHub's requirements (e.g., `v1.0.0`) - -## Security Notes - -- **GPG Keys**: Never commit private keys to version control. Use GitHub Secrets. -- **VT API Key**: Keep your VirusTotal API key secret and rotate periodically. -- **Release Artifacts**: All uploaded artifacts are publicly visible on your releases page. - -## License - -These scripts are part of the "The How-To Guide To Anonymity" project and follow the same licensing as the main repository.