Improve typography, layout and add more CI checks

.dockerignore

@@ -14,6 +14,8 @@ compose.yaml
 .github
 .gitignore
 .gitattributes
+.mdlrc
+.mdl_style.rb
 
 *.sw?
 *~

.github/workflows/ci.yml

@@ -35,6 +35,9 @@ jobs:
           ruby-version: ${{ env.RUBY }}
           bundler-cache: true
 
+      - name: Lint Markdown
+        run: bundle exec mdl README.md src
+
       - name: Run jekyll doctor
         run: bundle exec jekyll doctor
 
@@ -43,6 +46,9 @@ jobs:
         env:
           JEKYLL_ENV: production
 
+      - name: Check links
+        run: bundle exec htmlproofer ./_site --disable-external
+
       - name: Upload artifact
         if: github.repository == 'bleachbit/docs' && github.event_name != 'pull_request' && github.ref == 'refs/heads/gh-pages'
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

.mdl_style.rb

@@ -0,0 +1,20 @@
+all
+
+rule 'MD004', :style => :dash
+rule 'MD007', :indent => 2
+rule 'MD024', :allow_different_nesting => true
+# Question headings are fine
+rule 'MD026', :punctuation => '.,;:!'
+rule 'MD029', :style => :ordered
+
+# The layout renders page.title as the h1
+exclude_rule 'MD002'
+exclude_rule 'MD041'
+# Long lines are not rewrapped
+exclude_rule 'MD013'
+# kramdown keeps blockquotes split by a blank line separate
+exclude_rule 'MD028'
+# Raw HTML, like the video embed
+exclude_rule 'MD033'
+# "*New in BleachBit x.y.z*" notes
+exclude_rule 'MD036'

.mdlrc

@@ -0,0 +1,2 @@
+style '.mdl_style.rb'
+ignore_front_matter true

Dockerfile

@@ -18,9 +18,11 @@ ENV LANG=C.UTF-8 \
     BUNDLE_JOBS=4 \
     BUNDLE_RETRY=3
 
-# jekyll-last-modified-at reads each file's last commit date
+# git for jekyll-last-modified-at, which reads each file's last commit date.
+# libcurl for html-proofer, which loads it through ffi. The name is the trixie
+# one, older releases call it libcurl4.
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends git \
+    && apt-get install -y --no-install-recommends git libcurl4t64 \
     && rm -rf /var/lib/apt/lists/*
 
 

Gemfile

@@ -7,3 +7,8 @@ gem 'jekyll-seo-tag', '~> 2.9.0'
 gem 'jekyll-sitemap', '~> 1.4.0'
 gem 'tzinfo-data', :install_if => Gem.win_platform?
 gem 'wdm', '~> 0.2.0', :install_if => Gem.win_platform?
+
+group :test do
+    gem 'html-proofer', '~> 5.2.2'
+    gem 'mdl', '~> 0.18.1'
+end

Gemfile.lock

@@ -1,29 +1,63 @@
 GEM
   remote: https://rubygems.org/
   specs:
+    Ascii85 (2.0.1)
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
+    afm (1.0.0)
+    async (2.46.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.21)
     base64 (0.3.0)
+    benchmark (0.5.0)
     bigdecimal (4.1.3)
+    chef-utils (19.3.15)
+      concurrent-ruby
     colorator (1.1.0)
     concurrent-ruby (1.3.8)
+    console (1.38.0)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
     csv (3.3.6)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
+    ethon (0.18.0)
+      ffi (>= 1.15.0)
+      logger
     eventmachine (1.2.7)
     ffi (1.17.4-x64-mingw-ucrt)
     ffi (1.17.4-x86_64-linux-gnu)
+    ffi-win32-extensions (1.0.4)
+      ffi
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
     forwardable-extended (2.6.0)
-    google-protobuf (4.36.1-x64-mingw-ucrt)
+    google-protobuf (4.36.2-x64-mingw-ucrt)
       bigdecimal
       rake (~> 13.3)
-    google-protobuf (4.36.1-x86_64-linux-gnu)
+    google-protobuf (4.36.2-x86_64-linux-gnu)
       bigdecimal
       rake (~> 13.3)
+    hashery (2.1.2)
+    html-proofer (5.2.2)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      benchmark (~> 0.5)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
     http_parser.rb (0.8.1)
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
+    io-event (1.22.0)
     jekyll (4.4.1)
       addressable (~> 2.4)
       base64 (~> 0.2)
@@ -66,10 +100,38 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
+    mdl (0.18.1)
+      kramdown (~> 2.5)
+      kramdown-parser-gfm (~> 1.1)
+      mixlib-cli
+      mixlib-config
+      mixlib-shellout
+      uri
     mercenary (0.4.0)
+    mixlib-cli (2.1.8)
+    mixlib-config (3.0.27)
+      tomlrb
+    mixlib-shellout (3.4.10)
+      chef-utils
+    mixlib-shellout (3.4.10-x64-mingw-ucrt)
+      chef-utils
+      ffi-win32-extensions (~> 1.0.3)
+      win32-process (~> 0.9)
+      wmi-lite (~> 1.0)
+    nokogiri (1.19.4-x64-mingw-ucrt)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
+    pdf-reader (2.16.0)
+      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
+      afm (>= 0.2.1, < 2)
+      hashery (~> 2.0)
+      ttfunk
     public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
     rake (13.4.2)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
@@ -83,43 +145,69 @@ GEM
       google-protobuf (~> 4.31)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
+    tomlrb (2.0.4)
+    ttfunk (1.7.0)
+    typhoeus (1.6.0)
+      ethon (>= 0.18.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     tzinfo-data (1.2026.4)
       tzinfo (>= 1.0.0)
     unicode-display_width (2.6.0)
+    uri (1.1.1)
     wdm (0.2.0)
     webrick (1.9.2)
+    win32-process (0.10.0)
+      ffi (>= 1.0.0)
+    wmi-lite (1.0.7)
+    yell (2.2.2)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   x64-mingw-ucrt
   x86_64-linux
 
 DEPENDENCIES
+  html-proofer (~> 5.2.2)
   jekyll (~> 4.4.1)
   jekyll-last-modified-at (~> 1.3.2)
   jekyll-redirect-from (~> 0.16.0)
   jekyll-seo-tag (~> 2.9.0)
   jekyll-sitemap (~> 1.4.0)
+  mdl (~> 0.18.1)
   tzinfo-data
   wdm (~> 0.2.0)
 
 CHECKSUMS
+  Ascii85 (2.0.1) sha256=15cb5d941808543cbb9e7e6aea3c8ec3877f154c3461e8b3673e97f7ecedbe5a
   addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  afm (1.0.0) sha256=5bd4d6f6241e7014ef090985ec6f4c3e9745f6de0828ddd58bc1efdd138f4545
+  async (2.46.0) sha256=34f984733dbf63a997376346451ec995e858cacc3105e86ccfeaf8877b4f490b
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
   bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
+  chef-utils (19.3.15) sha256=1c537a9c85b55b6d897de8e8af6b66b017a6dfae2b5e7b25e0bf320637e0b86a
   colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38
   concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  console (1.38.0) sha256=35b82f59130e95e9be6b832d9e539c8b3988fc192e4a8e9a86ab4922f44ad5de
   csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
   em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8
+  ethon (0.18.0) sha256=b598afc9f30448cb068b850714b7d6948e941476095d04f90a4ac65b8d6efcb2
   eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972
   ffi (1.17.4-x64-mingw-ucrt) sha256=f6ff9618cfccc494138bddade27aa06c74c6c7bc367a1ea1103d80c2fcb9ed35
   ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  ffi-win32-extensions (1.0.4) sha256=9d01a511a7ea957d8f73a06892f3ccfa49dcb32be95c4edb86b5ba3103edea00
+  fiber-annotation (0.2.0) sha256=7abfadf1d119f508867d4103bf231c0354d019cc39a5738945dec2edadaf6c03
+  fiber-local (1.1.0) sha256=c885f94f210fb9b05737de65d511136ea602e00c5105953748aa0f8793489f06
+  fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
   forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97
-  google-protobuf (4.36.1-x64-mingw-ucrt) sha256=1ac6ce359ed6c40dcb06c2a5f7814fb8b8b44353c419be72d4ec09d97a903636
-  google-protobuf (4.36.1-x86_64-linux-gnu) sha256=e735a3f3d6596b1010013c2030778bc030770e659106fe7e4ae0f07631b551cb
+  google-protobuf (4.36.2-x64-mingw-ucrt) sha256=02b55d56c1c56a58a5e1cc3a7dda87e97343574ea5aa4f0e503379ba2647bbd1
+  google-protobuf (4.36.2-x86_64-linux-gnu) sha256=d25a820873e423f1d209ae8c672a4a28b019e2429debd0901d26670a0b4e14db
+  hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
+  html-proofer (5.2.2) sha256=6e5e63c89ef9413246eeffaeba8dd03db62546992d7a2b85d166ac2a5903a241
   http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
+  io-event (1.22.0) sha256=4936d38dfcf2291d897707fd94690f1a63fdb1ea3ab4fa63c6739fc6c61e1534
   jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1
   jekyll-last-modified-at (1.3.2) sha256=c4c08f137453e9b40764a769450870d05970e0934651a1fd9ef081f4a6e9a815
   jekyll-redirect-from (0.16.0) sha256=6635cae569ef9b0f90ffb71ec014ba977177fafb44d32a2b0526288d4d9be6db
@@ -133,9 +221,19 @@ CHECKSUMS
   liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3
   listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mdl (0.18.1) sha256=14c7ab8264bbeac4010bd54adb5d125cf1d29b3848c3b6bfacb239b8bc70037a
   mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138
+  mixlib-cli (2.1.8) sha256=e6f27be34d580f6ed71731ca46b967e57793a627131c1f6e1ed2dad39ea3bdf9
+  mixlib-config (3.0.27) sha256=d7748b1898e4f16502afec1de00b5ad65c6de405114b1b0c65ec61b1a9100148
+  mixlib-shellout (3.4.10) sha256=7c8a6c5a6c90922a8871ed682129c19c9b1a514eedea2e867077229e6a415f0c
+  mixlib-shellout (3.4.10-x64-mingw-ucrt) sha256=77defd5c445db201aa0f3e5602173953c538755c5626675f63dbca40e2042d2a
+  nokogiri (1.19.4-x64-mingw-ucrt) sha256=051da97b8eccfdb5444fed40246a35e10d7298b9efe759b4cd25455ea04c587e
+  nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
   pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589
+  pdf-reader (2.16.0) sha256=bf1b5564c085264d8279bde3cf1467778b75841494d20c0fe7da3dad475f3732
   public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
   rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
@@ -145,11 +243,19 @@ CHECKSUMS
   sass-embedded (1.104.1-x64-mingw-ucrt) sha256=b859211fa221e40a67da0463b258a6e7c54f4973621d2bad4b7f932c4a9a0bce
   sass-embedded (1.104.1-x86_64-linux-gnu) sha256=a9223bd34c4f5616412f4affbc8c450e5c547f69940ce42c92d23fca9111ea87
   terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91
+  tomlrb (2.0.4) sha256=262f77947ac3ac9b3366a0a5940ecd238300c553e2e14f22009e2afcd2181b99
+  ttfunk (1.7.0) sha256=2370ba484b1891c70bdcafd3448cfd82a32dd794802d81d720a64c15d3ef2a96
+  typhoeus (1.6.0) sha256=bacc41c23e379547e29801dc235cd1699b70b955a1ba3d32b2b877aa844c331d
   tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
   tzinfo-data (1.2026.4) sha256=22f5f02608f14938ab8b78513a70a22f0b0277614a07273d3bedb3ea45ece104
   unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
   wdm (0.2.0) sha256=c46d9dcb6d375199ca07465bc67669ee8f041aeaa55dd7dafe6de4dd97b27647
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+  win32-process (0.10.0) sha256=ad2d401c62f56f922f3fabb7a55fd2b65ea85becbad3b5d9093ffe59c386f542
+  wmi-lite (1.0.7) sha256=116ef5bb470dbe60f58c2db9047af3064c16245d6562c646bc0d90877e27ddda
+  yell (2.2.2) sha256=1d166f3cc3b6dc49a59778ea7156ed6d8de794c15106d48ffd6cbb061b9b26bc
+  zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
 
 BUNDLED WITH
-  4.0.20
+  4.0.21

Makefile

@@ -1,6 +1,6 @@
 # Makefile for BleachBit documentation site
 
-.PHONY: help clean serve serve-prod build install update spelling \
+.PHONY: help clean serve serve-prod build lint test install update spelling \
 	docker-serve docker-build docker-shell docker-down
 
 # Default target
@@ -11,6 +11,8 @@ help:
 	@echo "  serve    - Start local development server"
 	@echo "  serve-prod - Start local server without drafts"
 	@echo "  build    - Build the static site"
+	@echo "  lint     - Lint Markdown files"
+	@echo "  test     - Build and check the site for broken links"
 	@echo "  spelling - Check Markdown sources for spelling errors"
 	@echo "  install  - Install Ruby dependencies"
 	@echo "  update   - Update Ruby dependencies"
@@ -28,14 +30,19 @@ clean:
 	git gc
 	@echo "Clean complete."
 
+# Keep gems in the project instead of the global gem dir. Plain `bundle`
+# commands read this too, not only make.
+.bundle/config:
+	bundle config set --local path vendor/bundle
+
 # Install Ruby dependencies
-install:
+install: .bundle/config
 	@echo "Installing Ruby dependencies..."
 	bundle install
 	@echo "Dependencies installed"
 
 # Update Ruby dependencies
-update:
+update: .bundle/config
 	@echo "Updating Ruby dependencies..."
 	bundle update
 	@echo "Dependencies updated."
@@ -48,6 +55,14 @@ build:
 	bundle exec jekyll build
 	@echo "Site built in _site/"
 
+# Lint Markdown, see .mdl_style.rb for the rules
+lint:
+	bundle exec mdl README.md src
+
+# Check links, images and scripts in the built site
+test: build
+	bundle exec htmlproofer ./_site --disable-external
+
 # Check spelling in the Markdown sources
 spelling:
 	@bin/spellcheck

_config.yml

@@ -4,6 +4,8 @@ title: BleachBit Documentation
 tagline: Official user and developer guides
 description: Official user and developer guides for BleachBit, a free and open-source system cleaner.
 url: "https://docs.bleachbit.org"
+# Base for the "View source" link, page.path is relative to `source`
+source_url: "https://github.com/bleachbit/docs/blob/gh-pages/src"
 
 # if you wish to integrate disqus on pages set your shortname here
 disqus_shortname: ""

src/_includes/footer.html

@@ -1,4 +1,3 @@
-<p>
-    &copy; <a href="https://www.bleachbit.org">BleachBit</a> |
-    <a href="https://github.com/bleachbit/docs">Edit this documentation on GitHub</a>
+<p class="mb-0">
+    &copy; <a href="https://www.bleachbit.org">BleachBit</a>
 </p>

src/_includes/header.html

@@ -1,13 +1,13 @@
 <div class="d-flex align-items-center justify-content-between gap-2 mt-4 mb-2">
   <p class="fs-4 lh-sm mb-0">
-    <a class="brand" href="{{ '/' | relative_url }}">{{ site.title }}</a>
+    <a class="brand fw-bold" href="{{ '/' | relative_url }}">{{ site.title }}</a>
   </p>
   <button type="button" class="btn btn-sm btn-outline-secondary d-md-none" data-bs-toggle="offcanvas" data-bs-target="#docs-nav" aria-controls="docs-nav">Menu</button>
 </div>
 
-<p>
+<p class="text-secondary">
   <a href="https://www.bleachbit.org">Main site</a>
   | <a href="https://www.bleachbit.org/download">Download</a>
   | <a href="https://www.bleachbit.org/help">Get Help</a>
-  | <a href="https://github.com/bleachbit/docs">Edit this documentation</a>
+  | <a href="{{ site.source_url }}/{{ page.path }}">View page source</a>
 </p>

src/_includes/navigation.html

@@ -7,7 +7,7 @@
         {%- assign label = section[1] %}
         {%- assign docs = site.docs | where: 'category', category | sort: 'order' %}
         {%- if docs.size > 0 %}
-            <li class="nav-header text-uppercase fw-bold">{{ label }}</li>
+            <li class="pt-2 pb-1 ps-1 small text-uppercase fw-bold text-secondary">{{ label }}</li>
             {%- for doc in docs %}
                 <li class="nav-item">
                     <a {% if doc.url == page.url %}class="nav-link active" aria-current="page"{% else %}class="nav-link"{% endif %} href="{{ doc.url | relative_url }}">{{ doc.nav_title | default: doc.title }}</a>