diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml new file mode 100644 index 0000000..6eaed96 --- /dev/null +++ b/.github/workflows/build-pdf.yml @@ -0,0 +1,55 @@ +name: 🚀 Build guide PDF + +on: + workflow_dispatch: + pull_request: + paths: + - "docs/**" + - "mkdocs.yml" + - "scripts/build_guide_pdf.py" + - ".github/workflows/build-pdf.yml" + push: + branches: + - main + paths: + - "docs/**" + - "mkdocs.yml" + - "scripts/build_guide_pdf.py" + - ".github/workflows/build-pdf.yml" + +permissions: + contents: read + +jobs: + pdf: + name: MkDocs + print to PDF + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install MkDocs Material + run: pip install mkdocs-material + + - name: Install Chromium + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends chromium + + - name: Build PDF + env: + CI: true + run: python scripts/build_guide_pdf.py + + - name: Upload PDF artifact + uses: actions/upload-artifact@v4 + with: + name: guide-pdf + path: export/guide.pdf + if-no-files-found: error + retention-days: 90 diff --git a/.gitignore b/.gitignore index dfa3d39..4481382 100644 --- a/.gitignore +++ b/.gitignore @@ -1,130 +1,22 @@ -# Byte-compiled / optimized / DLL files +# Visual Studio (Windows) solution metadata +.vs/ +.vscode/ + +# Python (MkDocs, scripts/build_guide_pdf.py) __pycache__/ *.py[cod] *$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -pip-wheel-metadata/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -.python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ +.venv/ venv/ +env/ ENV/ -env.bak/ -venv.bak/ +.env -# Spyder project settings -.spyderproject -.spyproject +# Cache +.cache/ -# Rope project settings -.ropeproject - -# mkdocs documentation -/site +# MkDocs build output and local PDF export +site/ _site/ - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ +_site_test/ +export/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..123fc52 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +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). + +## [Unreleased] + +## [1.2.1] - 2026-04-11 + +### Added + +- GitHub Actions workflow **Build guide 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`. + +### 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 guide PDF** GitHub Actions workflow and the `guide-pdf` artifact. + +### 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. + +[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 diff --git a/README.md b/README.md index 2549b5f..2717d75 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,28 @@ This guide is an open-source non-profit initiative, [licensed](LICENSE.html) und **If you would like to make a donation to help this project, you can do so from [here](donations.html) where you will also find the project goals. All the donations will be strictly used within the context of this project. All donations and spendings are logged on the donations page.** -**View the guide:** -- [In your browser](guide.html) -- [PDF](export/guide.pdf) -- [OpenDocument (ODT)](export/guide.odt) -- Raw [Markdown](https://raw.githubusercontent.com/Anon-Planet/thgtoa/main/guide.md) +**Ways to read or export the guide** + +- **In your browser:** [Hitchhiker's Guide](https://www.anonymousplanet.org/guide/) (hosted site). After a local build you can also open `site/guide/index.html` directly. +- **Local HTML preview:** from the repository root, with Python 3 and [MkDocs Material](https://squidfunk.github.io/mkdocs-material/getting-started/) installed (`pip install mkdocs-material`), run `mkdocs serve` and open the URL printed in the terminal (for example `http://127.0.0.1:8000`). +- **PDF (local build):** from the repository root, using the same environment, run: + + ```bash + python scripts/build_guide_pdf.py + ``` + + This runs `mkdocs build` (output defaults to `./site`), then uses **Google Chrome** or **Microsoft Edge** in headless mode to print `site/guide/index.html` to **`export/guide.pdf`** (images and styling preserved). If the site is already built: `python scripts/build_guide_pdf.py --skip-mkdocs`. Other options: `--site-dir`, `--pdf`, and `python scripts/build_guide_pdf.py --help`. + + On **GitHub Actions**, the [Build guide PDF](https://github.com/Anon-Planet/thgtoa/actions/workflows/build-pdf.yml) workflow does the same using Chromium on Ubuntu when you push to `main` or open a pull request that touches the guide or build inputs; download the **`guide-pdf`** artifact from a successful run. You can also run it manually (**Actions** → **Build guide PDF** → **Run workflow**). +- **OpenDocument (ODT):** not produced by this repository (previous hosted export removed). +- **Raw Markdown (very large):** [docs/guide/index.md on GitHub](https://raw.githubusercontent.com/Anon-Planet/thgtoa/refs/heads/main/docs/guide/index.md) **Mirrors:** -- Hidden service: **Host down** +- Hidden service: **Host down** Feel free to submit issues using Github Issues with the repository link above. Criticism, opinions, and ideas are welcome! -Follow or contact us on: +**Follow or contact us on:** Discussion Channels: - Matrix room: diff --git a/docs/guide/index.md b/docs/guide/index.md index 508dce0..5134653 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -12,7 +12,13 @@ schema: - https://github.com/Anon-Planet - https://opencollective.com/anonymousplanetorg --- -![Anonymous Planet logo](../media/profile.png){ align=right } + +
+![Anonymous Planet logo](../media/profile.png) There are several ways you could read this guide: @@ -45,6 +51,8 @@ You could also install the [LibRedirect](https://libredirect.github.io/) extensi Finally note that this guide does mention and even recommends various commercial services (such as VPNs, CDNs, e-mail providers, hosting providers...) **but is not endorsed or sponsored by any of them in any way. There are no referral links and no commercial ties with any of these providers. This project is 100% non-profit and only relying on donations.** +
+ ## Requirements & Limitations - Understanding of the English language (in this case American English). @@ -719,7 +727,7 @@ As well as those interesting podcasts: -You should never share real individual experiences/details using your anonymous identities that could later lead to finding your real identity. You will see more details about this in the [Creating new identities][Creating new identities:] section. +You should never share real individual experiences/details using your anonymous identities that could later lead to finding your real identity. You will see more details about this in the [Creating new identities](#creating-new-identities) section. ### Your Face, Voice, Biometrics, and Pictures @@ -1966,7 +1974,7 @@ Remember that encryption with or without plausible deniability is not a silver b **See ** [[Wikiless]](https://wikiless.com/wiki/Rubber-hose_cryptanalysis) [[Archive.org]](https://web.archive.org/web/https://en.wikipedia.org/wiki/Rubber-hose_cryptanalysis) -CAUTION: Please see [**Appendix K: Considerations for using external SSD drives**](#appendix-k-considerations-for-using-external-ssd-drives) and [**Understanding HDD vs SSD**][Understanding HDD vs SSD:] sections if you consider storing such hidden VMs on an external SSD drive: +CAUTION: Please see [**Appendix K: Considerations for using external SSD drives**](#appendix-k-considerations-for-using-external-ssd-drives) and [**Understanding HDD vs SSD**](#understanding-hdd-vs-ssd) sections if you consider storing such hidden VMs on an external SSD drive: - **Do not use hidden volumes on SSD drives as this is not supported/recommended by Veracrypt**[^303]**.** @@ -2226,7 +2234,7 @@ You can mitigate this attack by doing the following (as recommended earlier): - Set up BIOS/UEFI/Firmware passwords to prevent any unauthorized boot of an unauthorized device. -- Some OSes and Encryption software have the [Anti Evil Maid (AEM)][Anti Evil Maid (AEM):] protection that can be enabled. This is the case with Windows/Veracrypt and QubeOS (only on Intel CPUs). +- Some OSes and Encryption software have the [Anti Evil Maid (AEM)](#anti-evil-maid-aem) protection that can be enabled. This is the case with Windows/Veracrypt and QubeOS (only on Intel CPUs). ##### Cold-Boot Attack @@ -3323,7 +3331,7 @@ Unfortunately, using Tor alone will raise the suspicion of many destinations' pl - If you intend to create persistent shared and authenticated identities on various services where access from Tor is hard, we recommend the **VPN over Tor** and **VPS VPN/Proxy over Tor** options (or VPN over Tor over VPN if needed). It might be a bit less secure against correlation attacks due to breaking Tor Stream isolation but provides much better convenience in accessing online resources than just using Tor. It is an "acceptable" trade-off IMHP if you are careful enough with your identity. - - **Note: It is becoming more common that mainstream services and CDNS are also blocking or hindering VPN users with captchas and other various obstacles**. **In that case, a self-hosted VPS with a VPN/Proxy over Tor is the best solution for this as having your own dedicated VPS guarantees you are the sole user of your IP and encounter little to no obstacles.** Consider a [Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux)][Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux):] if you want the least amount of issues (this will be explained in the next section in more details). + - **Note: It is becoming more common that mainstream services and CDNS are also blocking or hindering VPN users with captchas and other various obstacles**. **In that case, a self-hosted VPS with a VPN/Proxy over Tor is the best solution for this as having your own dedicated VPS guarantees you are the sole user of your IP and encounter little to no obstacles.** Consider a [Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux)](#self-hosted-vpnproxy-on-a-monerocash-paid-vps-for-users-more-familiar-with-linux) if you want the least amount of issues (this will be explained in the next section in more details). - If your intent however is just to browse random services anonymously without creating specific shared identities, using tor friendly services; or if you do not want to accept that trade-off in the earlier option. **Then we recommend using the Tor Only route to keep the full benefits of Stream Isolation (or Tor over VPN if you need to).** @@ -4371,7 +4379,7 @@ All the VMs behind the Whonix Gateway should now work fine without additional co **Take a post-install VirtualBox snapshot of your VMs.** -You are done and can now skip the rest to go to the [Getting Online][Getting Online:] part. +You are done and can now skip the rest to go to the [Getting Online](#getting-online) part. ## The Qubes Route @@ -4560,7 +4568,7 @@ Unfortunately, using Tor alone will raise the suspicion of many destinations' pl - If you intend to create persistent shared and authenticated identities on various services where access from Tor is hard, we recommend the **VPN over Tor** and **VPS VPN/Proxy over Tor** options (or VPN over Tor over VPN if needed). It might be a bit less secure against correlation attacks due to breaking Tor Stream isolation but provides much better convenience in accessing online resources than just using Tor. It is an "acceptable" trade-off IMHP if you are careful enough with your identity. - - **Note: It is becoming more common that mainstream services and CDNS are also blocking or hindering VPN users with captchas and other various obstacles**. **In that case, a self-hosted VPS with a VPN/Proxy over Tor is the best solution for this as having your own dedicated VPS guarantees you are the sole user of your IP and encounter little to no obstacles.** Consider a [Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux)][Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux):] if you want the least amount of issues (this will be explained in the next section in more details). + - **Note: It is becoming more common that mainstream services and CDNS are also blocking or hindering VPN users with captchas and other various obstacles**. **In that case, a self-hosted VPS with a VPN/Proxy over Tor is the best solution for this as having your own dedicated VPS guarantees you are the sole user of your IP and encounter little to no obstacles.** Consider a [Self-hosted VPN/Proxy on a Monero/Cash-paid VPS (for users more familiar with Linux)](#self-hosted-vpnproxy-on-a-monerocash-paid-vps-for-users-more-familiar-with-linux) if you want the least amount of issues (this will be explained in the next section in more details). - If your intent however is just to browse random services anonymously without creating specific shared identities, using tor friendly services; or if you do not want to accept that trade-off in the earlier option. **Then we recommend using the Tor Only route to keep the full benefits of Stream Isolation (or Tor over VPN if you need to).** @@ -5223,7 +5231,7 @@ Phone verification is advertised by most platforms to verify you are human. But Most platforms (including the privacy-oriented ones such as Signal/Telegram/Proton will require a phone number to register, and most countries now make it mandatory to submit a proof of ID to register[^381]. -Fortunately, this guide explained earlier how to get a number for these cases: [Getting an anonymous Phone number][Getting an anonymous Phone number:]. +Fortunately, this guide explained earlier how to get a number for these cases: [Getting an anonymous Phone number](#getting-an-anonymous-phone-number). ### E-Mail verification @@ -5731,7 +5739,7 @@ Legend: - "Indirectly": This means they do require something but indirectly through a third-party system (Financial KYC for example). -- **See [The Real-Name System][Checking if your Tor Exit Node is terrible:] for essential information. See below for details.** +- **See [The Real-Name System](#the-real-name-system) for essential information. See below for details.** **Below you'll find a list of "problematic services". If they're not below, it means there are no issues at all with anything (like Briar for example)** @@ -6215,7 +6223,7 @@ You are going to have to find a separate way to post there using at least seven **Crypto Wallets** -Use any crypto wallet app within the Windows Virtual Machine. But be careful not to transfer anything toward an Exchange or a known Wallet. Crypto is in most cases NOT anonymous and can be traced back to you when you buy/sell any (remember the [Your Cryptocurrencies transactions][Your Cryptocurrencies transactions:] section). +Use any crypto wallet app within the Windows Virtual Machine. But be careful not to transfer anything toward an Exchange or a known Wallet. Crypto is in most cases NOT anonymous and can be traced back to you when you buy/sell any (remember the [Your Crypto Transactions](#your-crypto-transactions) section). **If you really want to use Crypto, use Monero which is the only one with reasonable privacy/anonymity.** @@ -6269,7 +6277,7 @@ For these reasons, it is always important to check the claims of various apps. O #### Roll your own crypto -See the [Bad Cryptography][Bad Cryptography:] section at the start of this guide. +See the [Bad Cryptography](#bad-cryptography) section at the start of this guide. **Always be cautious of apps rolling their own crypto until it has been reviewed by many in the crypto community (or even better published and peer-reviewed academically)**. Again, this is harder to verify with closed-source proprietary apps. @@ -6293,7 +6301,7 @@ Zero-Access Encryption[^411] at rest is used when you store data at some provide Zero-Access encryption is an added feature/companion to e2ee but is applied mainly to data at rest and not communications. -Examples of this issue would be iMessage and WhatsApp, see the [Your Cloud backups/sync services][Your Cloud backups/sync services:] at the start of this guide. +Examples of this issue would be iMessage and WhatsApp, see the [Your Cloud Backup & Sync Services](#your-cloud-backup-sync-services) at the start of this guide. So again, it is best to prefer Apps/Providers that do offer Zero-Access Encryption at rest and cannot read/access any of your data/metadata even at rest and not only limited to communications. @@ -6301,7 +6309,7 @@ Such a feature would have prevented important hacks such as the Cambridge Analyt #### Metadata Protection -Remember the [Your Metadata including your Geo-Location][Your Metadata including your Geo-Location:] section. End-to-end Encryption is one thing, but it does not necessarily protect your metadata. +Remember the [Your Metadata](#your-metadata) section (including geo-location). End-to-end Encryption is one thing, but it does not necessarily protect your metadata. For Instance, WhatsApp might not know what you are saying but they might know who you are talking to, how long and when you have been talking to someone, who else is in groups with you, and if you transferred data with them (such as large files). @@ -7087,7 +7095,7 @@ Here is a comparative table of recommended/included software compiled from vario **Legend:** * Not recommended but mentioned. N/A = Not Included or absence of recommendation for that software type. (L)= Linux Only but can maybe be used on Windows/macOS through other means (HomeBrew, Virtualization, Cygwin). (?)= Not tested but open-source and could be considered. -**In all cases, we strongly recommend only using such applications from within a VM or Tails to prevent as much leaking as possible. If you do not, you will have to sanitize those documents carefully before publishing (See [Removing Metadata from Files/Documents/Pictures][Removing Metadata from Files/Documents/Pictures:]).** +**In all cases, we strongly recommend only using such applications from within a VM or Tails to prevent as much leaking as possible. If you do not, you will have to sanitize those documents carefully before publishing (See [Removing Metadata from Files/Documents/Pictures](#removing-metadata-from-filesdocumentspictures)).** ### Communicating sensitive information @@ -7123,7 +7131,7 @@ Without SecureDrop you could consider: What you should avoid: -- Do not send physical materials using the post due to the risk of leaving DNA/Fingerprints or other traceable information (see [Cash-Paid VPN (preferred)][Cash/Monero-Paid VPN:]). +- Do not send physical materials using the post due to the risk of leaving DNA/Fingerprints or other traceable information (see [Cash-Paid VPN (preferred)](#cashmonero-paid-vpn)). - Do not use methods linked to a phone number (even a burner one) such as Signal/WhatsApp/Telegram. @@ -7207,7 +7215,7 @@ To do this, when mounting the Decoy Volume, select Mount Options and Check the " - If you are mounting the hidden volume from your Host OS (**not recommended**), you should erase all traces of this hidden volume everywhere after use. There could be traces in various places (system logs, file systems journaling, recent documents in your applications, indexing, registry entries...). Refer to the [Some additional measures against forensics](#some-additional-measures-against-forensics) section of this guide to remove such artifacts. Especially on Windows. Instead, you should mount them on your Guest VMs. With Virtualbox for instance, you could take a snapshot of the VM before opening/working the hidden volume and then restore the snapshot before opening/working on it after use. This should erase the traces of its presence and mitigate the issue. Your Host OS might keep logs of the USB key being inserted but not of the hidden volume usage. Therefore, we do not recommend using these from your host OS. -- Do not store these on external SSD drives if you are not sure you can use Trim on them (see the [Understanding HDD vs SSD][Understanding HDD vs SSD:] section). +- Do not store these on external SSD drives if you are not sure you can use Trim on them (see the [Understanding HDD vs SSD](#understanding-hdd-vs-ssd) section). ### Full Disk/System Backups @@ -8599,7 +8607,7 @@ Please keep thinking for yourself, use critical thinking, and keep an open mind. **"In the end the Party would announce that two and two made five, and you would have to believe it" -- George Orwell, 1984, Book One, Chapter Seven.** -Consider helping others (see [Helping others staying anonymous][Helping others staying anonymous:]) +Consider helping others (see [Helping others staying anonymous](#helping-others-staying-anonymous)) # Donations @@ -9259,7 +9267,7 @@ Both these tools can be used for cleaning many things such as: - Various logs -- The free (unallocated) space of your hard drive][^462]. +- The free (unallocated) space of your hard drive[^462]. - Secure deletion of files @@ -10109,7 +10117,7 @@ Even the most basic controls (supervision or parental) will send out detailed ap This method is the one we would recommend in those cases. -It is relatively easy for your adversary to prevent this by setting up firmware BIOS/UEFI (see [Bios/UEFI/Firmware Settings of your laptop][Bios/UEFI/Firmware Settings of your laptop:]) controls but usually most adversaries will overlook this possibility which requires more technical knowledge than just relying on Software. +It is relatively easy for your adversary to prevent this by setting up firmware BIOS/UEFI (see [Bios/UEFI/Firmware Settings of your laptop](#biosuefifirmware-settings-of-your-laptop)) controls but usually most adversaries will overlook this possibility which requires more technical knowledge than just relying on Software. This method could even decrease suspicion and increase your plausible deniability as your adversaries think they have things under control and that everything appears normal in their reports. @@ -10998,7 +11006,7 @@ As mentioned before in this guide multiple times, we strongly recommend the use - But what if the service you want does not accept Monero but does accept a more mainstream cryptocurrency such as Bitcoin (BTC) or Ethereum (ETH)? -**Bitcoin and other "mainstream cryptocurrencies" are not anonymous at all (Remember [Your Cryptocurrencies transactions][Your Cryptocurrencies transactions:]) and you should never ever purchase, for example, Bitcoin from an exchange and then use these directly for purchasing services anonymously. This will not work, and the transaction can be traced easily.** +**Bitcoin and other "mainstream cryptocurrencies" are not anonymous at all (Remember [Your Crypto Transactions](#your-crypto-transactions)) and you should never ever purchase, for example, Bitcoin from an exchange and then use these directly for purchasing services anonymously. This will not work, and the transaction can be traced easily.** - **Stay away from so-called "private" mixers, tumblers and coinjoiners.** You might think this is a good idea, but not only are they useless with cryptocurrencies such as BTC/ETH/LTC, they are also dangerous. They take custody of your coins. Use Monero to anonymize your crypto. Do not use a normal KYC-enabled exchange to buy/sell your Monero (such as Kraken), since this information on your purchases and withdrawals (for intended use) are retained in the exchange. Instead, use a P2P exchange that doesn't require KYC such as what can be found on . @@ -11438,7 +11446,7 @@ Remember this should only be done on a secure environment such as VM behind the Here is a checklist of things to verify before sharing information to anyone: -- Check the files for any metadata: see [Removing Metadata from Files/Documents/Pictures][Removing Metadata from Files/Documents/Pictures:] +- Check the files for any metadata: see [Removing Metadata from Files/Documents/Pictures](#removing-metadata-from-filesdocumentspictures) - Check the files for anything malicious: see [Appendix T: Checking files for malware](#appendix-t-checking-files-for-malware) diff --git a/docs/mirrors/index.md b/docs/mirrors/index.md index 06db8ef..469cc71 100644 --- a/docs/mirrors/index.md +++ b/docs/mirrors/index.md @@ -25,6 +25,12 @@ schema: - [Archive.today](https://archive.fo/anonymousplanet.org) - [Archive.today over Tor](http://archiveiya74codqgiixo33q62qlrqtkgmcitqx5u2oeqnmn5bpcbiyd.onion/anonymousplanet.org) +!!! Note "PDF export (single file)" + + The guide is also available as a **PDF** (images and layout preserved). It is built automatically in GitHub Actions: open [**Build guide PDF**](https://github.com/Anon-Planet/thgtoa/actions/workflows/build-pdf.yml) on the [**thgtoa** source repository](https://github.com/Anon-Planet/thgtoa), pick a successful run, and download the **`guide-pdf`** artifact. You can start a fresh build anytime (**Actions** → **Build guide PDF** → **Run workflow**). + + To produce the same file locally, clone the repository and run `python scripts/build_guide_pdf.py` (Python, [MkDocs Material](https://squidfunk.github.io/mkdocs-material/getting-started/), and **Google Chrome** or **Microsoft Edge** required). More detail is in the [repository README](https://github.com/Anon-Planet/thgtoa#ways-to-read-or-export-the-guide). + !!! Note "Our official git mirrors" - [Github](https://github.com/anon-planet) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..8a661c3 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,55 @@ +/* Title sheet: visible only when printing / generating PDF (not on screen). */ +.pdf-title-page { + display: none; +} + +@media print { + .pdf-title-page { + display: block; + box-sizing: border-box; + text-align: center; + padding: 5rem 2rem 4rem; + page-break-after: always; + } + + .pdf-title-page__title { + font-size: 1.65rem; + font-weight: 700; + line-height: 1.25; + margin: 0 0 1.25rem; + } + + .pdf-title-page__subtitle { + font-size: 1.05rem; + line-height: 1.4; + margin: 0 0 2rem; + } + + .pdf-title-page__meta { + font-size: 0.95rem; + font-style: normal; + margin: 0; + } +} + +/* Guide landing: small floating logo so opening copy flows beside it (HTML + PDF). */ +.guide-intro-lead { + overflow: auto; +} + +.guide-intro-lead > p:first-child { + margin-top: 0; +} + +.guide-intro-lead > p:first-child img { + float: right; + max-width: 6.5rem; + height: auto; + margin: 0 0 0.5rem 1rem; +} + +@media print { + .guide-intro-lead > p:first-child img { + max-width: 5rem; + } +} diff --git a/mkdocs.yml b/mkdocs.yml index 8e8ed23..82a193b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,9 @@ plugins: # - git-authors: {} # - git-latest-release: {} +extra_css: + - stylesheets/extra.css + extra: social: - icon: simple/mastodon diff --git a/scripts/build_guide_pdf.py b/scripts/build_guide_pdf.py new file mode 100644 index 0000000..7ad142c --- /dev/null +++ b/scripts/build_guide_pdf.py @@ -0,0 +1,161 @@ +#!/usr/bin/env python3 +"""Build the MkDocs site, then render docs/guide/ to a single PDF via a Chromium-based browser. + +Uses headless Chrome/Edge print-to-PDF (embeds images). WeasyPrint-based mkdocs-with-pdf is +omitted here because it needs GTK/Pango (awkward on Windows). + +Usage (from repo root): + python scripts/build_guide_pdf.py + python scripts/build_guide_pdf.py --site-dir build/html --pdf export/guide.pdf +""" + +from __future__ import annotations + +import argparse +import os +import shutil +import subprocess +import sys +import time +from pathlib import Path + + +def repo_root() -> Path: + return Path(__file__).resolve().parent.parent + + +def find_chromium_executable() -> Path | None: + if sys.platform == "win32": + paths = [ + Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Microsoft/Edge/Application/msedge.exe", + Path(os.environ.get("LOCALAPPDATA", "")) / "Microsoft/Edge/Application/msedge.exe", + Path(os.environ.get("PROGRAMFILES", "")) / "Google/Chrome/Application/chrome.exe", + Path(os.environ.get("PROGRAMFILES(X86)", "")) / "Google/Chrome/Application/chrome.exe", + Path(os.environ.get("LOCALAPPDATA", "")) / "Google/Chrome/Application/chrome.exe", + ] + for p in paths: + if p.is_file(): + return p + for name in ("chrome", "msedge"): + w = shutil.which(name) + if w: + return Path(w) + elif sys.platform == "darwin": + for p in ( + "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", + "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", + "/Applications/Chromium.app/Contents/MacOS/Chromium", + ): + if os.path.isfile(p): + return Path(p) + for name in ("google-chrome-stable", "google-chrome", "chromium-browser", "chromium", "chrome"): + w = shutil.which(name) + if w: + return Path(w) + return None + + +def run_mkdocs(site_dir: Path) -> None: + site_dir.mkdir(parents=True, exist_ok=True) + subprocess.run( + [sys.executable, "-m", "mkdocs", "build", "-d", str(site_dir)], + cwd=repo_root(), + check=True, + ) + + +def print_to_pdf(browser: Path, html_file: Path, pdf_out: Path) -> Path: + """Write PDF to ``pdf_out``. Uses a temp file first so an open ``guide.pdf`` on Windows + does not block the build: if the final path is locked, writes ``guide-new.pdf`` instead. + """ + pdf_out.parent.mkdir(parents=True, exist_ok=True) + partial = pdf_out.parent / f".{pdf_out.name}.writing" + partial.unlink(missing_ok=True) + + uri = html_file.resolve().as_uri() + # Chromium headless print; allow time for fonts/images on very large pages. + cmd = [str(browser)] + if os.environ.get("CI"): + # GitHub Actions / other CI runners often need these for Chromium to start. + cmd += [ + "--no-sandbox", + "--disable-setuid-sandbox", + "--disable-dev-shm-usage", + ] + cmd += [ + "--headless=new", + "--disable-gpu", + "--no-pdf-header-footer", + f"--print-to-pdf={partial.resolve()}", + uri, + ] + subprocess.run(cmd, check=True, timeout=600) + deadline = time.time() + 120 + while time.time() < deadline: + if partial.exists() and partial.stat().st_size > 0: + break + time.sleep(0.25) + else: + partial.unlink(missing_ok=True) + raise RuntimeError(f"PDF was not written to {partial}") + + try: + if pdf_out.exists(): + pdf_out.unlink() + except PermissionError: + fallback = pdf_out.with_name(f"{pdf_out.stem}-new{pdf_out.suffix}") + fallback.unlink(missing_ok=True) + partial.replace(fallback) + return fallback + + partial.replace(pdf_out) + return pdf_out + + +def main() -> int: + root = repo_root() + ap = argparse.ArgumentParser(description="Build MkDocs + single-page guide PDF.") + ap.add_argument( + "--site-dir", + type=Path, + default=root / "site", + help="MkDocs output directory (default: ./site)", + ) + ap.add_argument( + "--pdf", + type=Path, + default=root / "export" / "guide.pdf", + help="Output PDF path (default: ./export/guide.pdf)", + ) + ap.add_argument("--skip-mkdocs", action="store_true", help="Reuse existing site dir; only run print-to-pdf.") + args = ap.parse_args() + + guide_html = args.site_dir / "guide" / "index.html" + if not args.skip_mkdocs: + run_mkdocs(args.site_dir) + if not guide_html.is_file(): + print(f"Missing {guide_html}; run without --skip-mkdocs first.", file=sys.stderr) + return 1 + + browser = find_chromium_executable() + if not browser: + print( + "No Chromium-based browser found (Chrome, Edge, or Chromium). " + "Install Google Chrome or Microsoft Edge, or add Chromium to PATH.", + file=sys.stderr, + ) + return 1 + + out = print_to_pdf(browser, guide_html, args.pdf) + size_kb = out.stat().st_size // 1024 + print(f"Wrote {out.resolve()} ({size_kb} KiB)") + if out.resolve() != args.pdf.resolve(): + print( + f"Note: {args.pdf.name} was in use; close it and rename or replace with the file above.", + file=sys.stderr, + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())