P2Poolv2 Documentation

The source for https://docs.p2poolv2.org. The site uses Jekyll with the Just the Docs theme, AsciiDoc pages via jekyll-asciidoc, and PlantUML diagrams via asciidoctor-diagram.

Contents

This documentation project is a work in progress, and the rendered site is not published yet. For convenience, here are direct AsciiDoc links to a few notable pages in progress.

• P2Poolv2 Documentation (docs home page)

• Getting Started

• Single Miner Story

Additional Contents

_config.yml                    site, theme and Asciidoctor settings
architecture/                  sections (sample content for now)
_snippets/                     files pulled into pages with include::
_plantuml/p2poolv2.config      brand skin applied to every PlantUML diagram
_sass/custom/setup.scss        the brand palette and fonts
_sass/color_schemes/p2poolv2.scss  Just the Docs color scheme and code colors
_sass/custom/custom.scss       brand overrides and styles for AsciiDoc blocks
_includes/head_custom.html     favicon and self-hosted fonts
assets/images/                 logo and favicon, from ../website/assets
assets/fonts/, assets/css/fonts.css  Inter and JetBrains Mono, from ../website
.github/workflows/pages.yml    build and deploy to GitHub Pages
CNAME                          docs.p2poolv2.org

Working on It

You need Ruby (see .ruby-version), Bundler, and a Java runtime for PlantUML. Class, component, and activity diagrams also need Graphviz (dot). The PlantUML jar itself comes from the asciidoctor-diagram-plantuml gem.

bundle install
bundle exec jekyll serve --livereload

Then open http://localhost:4000. If a diagram does not update, run bundle exec jekyll clean and remove .asciidoctor/.

Checking Links

The Rakefile builds the site and runs html-proofer over _site/, checking links between pages, #anchor links, and image paths.

bundle exec rake                 # build, then check internal links
bundle exec rake check:external  # also check links to other sites
bundle exec rake build           # build only

When a link is broken, the task fails and lists the page and line in _site/ where the link appears. Run the internal check before pushing. The external check requests every outside URL, so it is slower, and it can fail when a site is down or rate-limits the requests.

Writing Pages

See Writing documentation. In short: a .adoc file with = Title and :page-nav_order:, :page-parent: and :page-has_children: attributes for the sidebar, and [plantuml, name, svg] blocks for diagrams.

Brand

The colors, logo, favicon, and fonts match the landing page in ../website, which takes them from ../logos/p2poolv2-brand-pack. The four brand colors (Bitcoin Orange #F7931A, Black #0B0B0C, Near Black #121212, and White) are the only colors on the site, including in code highlighting and diagrams. They are defined once in _sass/custom/setup.scss (and, for diagrams, in _plantuml/p2poolv2.config); every shade is one of them at reduced opacity. White on orange fails contrast, so anything on a filled orange surface is black. The site loads nothing from a third party: the fonts are self-hosted.

Publishing

Pushing to main runs .github/workflows/pages.yml, which builds the site and deploys it to GitHub Pages. In the repository settings, set Pages > Source to "GitHub Actions" and the custom domain to docs.p2poolv2.org. Then point a CNAME DNS record for docs at p2poolv2.github.io.