LinuxCNC · grandixximo · May 31, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/debian/copyright b/debian/copyright
@@ -411,6 +411,11 @@ Files: share/qtvcp/images/widgets/writer/icons/*
 Copyright: 2013 Yusuke Kamiyamane
 License: CC-BY-3.0
 
+Files: docs/src/admon-*.svg
+Copyright: 2019-2024 The Bootstrap Authors
+License: Expat
+Comment: Admonition icons from Bootstrap Icons, https://github.com/twbs/icons.
+
 Files: unit_tests/catch.hpp
 Copyright: 2019 Two Blue Cubes Ltd. All rights reserved.
 License: Boost-1.0

diff --git a/docs/README.adoc b/docs/README.adoc
@@ -19,6 +19,13 @@ the index.tmpl.
 `po4a.cfg` is used to map source files to translated documentation when
 generating translated files using the files in `docs/po/`.
 
+Every translated HTML page is emitted regardless of completeness; the
+topbar language-switcher post-process greys out per-page entries whose
+`.po` coverage falls below `POKEEP` percent (default 80). Override at
+build time: `make POKEEP=30 docs` to surface in-progress translations,
+`make POKEEP=0 docs` to keep every entry clickable. See
+`docs/src/code/contributing-to-linuxcnc.adoc` for details.
+
 == Notes on LinuxCNC documentation
 
 The main LinuxCNC Makefile can optionally build the documentation and

diff --git a/docs/po4a.cfg b/docs/po4a.cfg
@@ -26,6 +26,7 @@
 [type: AsciiDoc_def] src/Master_Getting_Started.adoc $lang:build/adoc/$lang/Master_Getting_Started.adoc
 [type: AsciiDoc_def] src/Master_Integrator.adoc $lang:build/adoc/$lang/Master_Integrator.adoc
 [type: xhtml_def] src/index.tmpl $lang:build/adoc/$lang/index.tmpl
+[type: Text_def] src/topbar-labels $lang:build/adoc/$lang/topbar-labels
 [type: AsciiDoc_def] src/help/rtfaults.adoc $lang:build/adoc/$lang/help/rtfaults.adoc
 [type: AsciiDoc_def] src/help/tklinuxcnc.adoc $lang:build/adoc/$lang/help/tklinuxcnc.adoc
 [type: AsciiDoc_def] src/code/adding-configs.adoc $lang:build/adoc/$lang/code/adding-configs.adoc
@@ -79,7 +80,7 @@
 [type: AsciiDoc_def] src/examples/spindle.adoc $lang:build/adoc/$lang/examples/spindle.adoc
 [type: AsciiDoc_def] src/gcode/coordinates.adoc $lang:build/adoc/$lang/gcode/coordinates.adoc
 [type: AsciiDoc_def] src/gcode/g-code.adoc $lang:build/adoc/$lang/gcode/g-code.adoc
-[type: xhtml_def] src/gcode.html $lang:build/html/$lang/gcode.html
+[type: xhtml_def] src/gcode.html.in $lang:build/adoc/$lang/gcode-raw.html
 [type: AsciiDoc_def] src/gcode/machining-center.adoc $lang:build/adoc/$lang/gcode/machining-center.adoc
 [type: AsciiDoc_def] src/gcode/m-code.adoc $lang:build/adoc/$lang/gcode/m-code.adoc
 [type: AsciiDoc_def] src/gcode/o-code.adoc $lang:build/adoc/$lang/gcode/o-code.adoc

diff --git a/docs/src/.gitignore b/docs/src/.gitignore
@@ -0,0 +1 @@
+docinfo-header.html
diff --git a/docs/src/Submakefile b/docs/src/Submakefile
diff --git a/docs/src/admon-caution.svg b/docs/src/admon-caution.svg
diff --git a/docs/src/admon-important.svg b/docs/src/admon-important.svg
diff --git a/docs/src/admon-note.svg b/docs/src/admon-note.svg
diff --git a/docs/src/admon-tip.svg b/docs/src/admon-tip.svg
diff --git a/docs/src/admon-warning.svg b/docs/src/admon-warning.svg
diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc
@@ -194,6 +194,14 @@ The most commonly used arguments are:
   Disable building the translated documentation for all available languages.
   The building of the translated documentation takes a huge amount of time, so it is recommend to skip that if not really needed.
 
+Translation completeness threshold::
+  `make POKEEP=N docs`. Per-master threshold (percent) below which a
+  language-switcher entry is greyed out on the corresponding page.
+  Translated HTML is always emitted; this knob only affects whether
+  the entry stays clickable. Default 80. Translators can lower the
+  threshold (`POKEEP=30`, `POKEEP=0`) to make their work-in-progress
+  show up as live links. See the contributing guide for details.
+
 [[make-arguments]]
 ==== `make` arguments
 

diff --git a/docs/src/code/contributing-to-linuxcnc.adoc b/docs/src/code/contributing-to-linuxcnc.adoc
@@ -260,6 +260,31 @@ https://hosted.weblate.org/projects/linuxcnc/
 Documentation on how to use Weblate is here:
 https://docs.weblate.org/en/latest/user/basic.html
 
+=== Previewing a translation locally
+
+Every translated HTML page is emitted regardless of how much of its
+source has actually been translated. The topbar language switcher
+greys out entries whose underlying `.po` coverage for that specific
+master falls below *80%* by default. Greyed entries are still in the
+DOM (so deep links keep working) but rendered as plain text rather
+than clickable links, signalling to readers that the page is mostly
+English.
+
+If you are actively translating and want your work-in-progress to
+appear as a live link on its companion pages, lower the threshold at
+build time:
+
+[source,sh]
+----
+cd src
+make POKEEP=30 docs   # any page >= 30% translated stays clickable
+make POKEEP=0  docs   # everything clickable, even untouched pages
+----
+
+`POKEEP` is consumed by the post-process pass that walks every HTML
+file once at the end of the build. The default value, used by the
+published build, is 80.
+
 == Other ways to contribute
 
 There are many ways to contribute to LinuxCNC, that are not addressed

diff --git a/docs/src/docinfo-header.html.in b/docs/src/docinfo-header.html.in
@@ -0,0 +1,17 @@
+<header id="lcnc-topbar" class="lcnc-topbar">
+  <a class="lcnc-topbar-home" href="{lcnc-cssrel}index.html">
+    <img src="{lcnc-cssrel}lcnc-docs.svg" alt="LinuxCNC Documentation">
+  </a>
+  <nav class="lcnc-topbar-links">
+    <a data-lcnc-link="0" href="https://linuxcnc.org">LinuxCNC Home Page</a>
+    <span class="lcnc-sep" aria-hidden="true">&bull;</span>
+    <a data-lcnc-link="1" href="https://wiki.linuxcnc.org/cgi-bin/wiki.pl">Wiki</a>
+    <span class="lcnc-sep" aria-hidden="true">&bull;</span>
+    <a data-lcnc-link="2" href="https://forum.linuxcnc.org">Forum</a>
+    <span class="lcnc-sep" aria-hidden="true">&bull;</span>
+    <a data-lcnc-link="3" href="https://github.com/LinuxCNC/linuxcnc">Source</a>
+    <span class="lcnc-sep" aria-hidden="true">&bull;</span>
+    <a data-lcnc-link="4" href="{lcnc-cssrel}en/gcode.html">G-Code Quick Reference</a>
+  </nav>
+@LANGUAGE_SWITCHER@
+</header>
diff --git a/docs/src/gcode.html → docs/src/gcode.html.in b/docs/src/gcode.html → docs/src/gcode.html.in
@@ -197,28 +197,6 @@
     }
 }
 
-function fixup_urls() {
-var links=document.evaluate('//a[@href]', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
-    for(var i=0; i<links.snapshotLength; i++) {
-        var it = links.snapshotItem(i);
-        it.setAttribute('href',
-            "https://linuxcnc.org/docs/devel/html/" + it.getAttribute('href'));
-    }
-}
-
-// In the LinuxCNC package, gcode/g-code.html is (probably) not included.  In this
-// case, fix up the links to point at the online version instead of a local
-// version
-if(document.location.protocol == "file:") {
-    try {
-        var x = document.implementation.createDocument("", "", null);
-        x.load("gcode/g-code.html");
-        x.onerror = fixup_urls;
-    } catch(err) {
-        fixup_urls();
-    }
-}
-
 // --></script>
 
 </body></html>
diff --git a/docs/src/index.tmpl b/docs/src/index.tmpl
@@ -15,33 +15,10 @@
   <img src="../linuxcnc-logo-chips.png" alt="LinuxCNC Logo" width="175"/>
 </div>
 
-@TRANSLATIONS@
-<p>Translations:
-<a href="../ar/">Arabic</a>
-<a href="../de/">Deutsch</a>
-<a href="../es/">Espa&ntilde;ol</a>
-<a href="../fr/">Français</a>
-<a href="../nb/">Norsk bokm&aring;l</a>
-<a href="../ru/">Russian</a>
-<a href="../sv/">Svensk</a>
-<!-- <a href="../ta/">Tamil</a> -->
-<a href="../uk/">Ukranian</a>
-<a href="../zh_CN/">中文</a>
-</p>
-@ENDTRANSLATIONS@
-
 <!-- <h3 align="center">LinuxCNC version <strong>@VERSION@</strong></h3>
 <h2>Documentation</h2> -->
 <h2>LinuxCNC version <strong>@VERSION@</strong> Documentation</h2>
 
-<div style="margin-top: 0em; margin-bottom: 1em; line-height: 150%">
-<p><a href="https://linuxcnc.org">LinuxCNC Home Page</a>  &bull;
-<a href="https://wiki.linuxcnc.org/cgi-bin/wiki.pl">Wiki</a> &bull;
-<a href="https://forum.linuxcnc.org">Forum</a> &bull;
-<a href="https://github.com/LinuxCNC/linuxcnc">Source</a> &bull;
-<a href="gcode.html">G-Code Quick Reference</a></p>
-</div>
-
 <h3>Getting Started &amp; Configuration</h3>
 
 <details open="open">

diff --git a/docs/src/lang-labels b/docs/src/lang-labels
@@ -0,0 +1,11 @@
+# Native display labels for the docs language switcher.
+# Format: <tag> <whitespace> <native name>.  A language listed in
+# po4a.cfg [po4a_langs] but absent here falls back to its bare tag.
+en    English
+de    Deutsch
+es    Español
+fr    Français
+nb    Norsk
+ru    Русский
+uk    Українська
+zh_CN 中文