mkdocs-primer 0.1.2__tar.gz → 0.2.0__tar.gz

{mkdocs_primer-0.1.2 → mkdocs_primer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mkdocs-primer
-Version: 0.1.2
+Version: 0.2.0
 Summary: A MkDocs theme built on GitHub's Primer design system
 Project-URL: Homepage, https://github.com/olegshulyakov/mkdocs-primer
 Project-URL: Source, https://github.com/olegshulyakov/mkdocs-primer
@@ -47,7 +47,7 @@ theme:
 - Syntax highlighting mapped onto Primer's `prettylights` variables, so code colors follow the color mode. Works with both `pymdownx.highlight` and `codehilite`.
 - Copy buttons for Pygments code blocks and an accessible back-to-top control that respects reduced-motion preferences.
 - Admonitions styled after GitHub's alerts. The `admonition` extension ships no CSS and `@primer/css` has no rule for it, so most themes render `!!! note` undecorated.
-- Sidebar navigation with unlimited nesting, prev/next links, a search results page, and a 404 page.
+- Sidebar navigation with unlimited nesting, collapsed down to the section the reader is in, plus a breadcrumb trail, prev/next links, a search results page, and a 404 page.
 - Optional Workbox-powered offline support for sites served over HTTPS.
 - "Improve this page" footer, as in the Jekyll theme, with a "Last updated" line when `mkdocs-git-revision-date-localized` is enabled.
 - Native support for the plugins that need it: `mkdocs-section-index` (section labels render as links) and `mkdocs-static-i18n` (translated pages get the right `<html lang>` and can use the header language selector). See [Plugins](https://olegshulyakov.github.io/mkdocs-primer/guide/plugins/).
@@ -58,8 +58,10 @@ theme:
 | --- | --- | --- |
 | `logo` | `null` | Image shown beside the site name, relative to `docs_dir`. |
 | `favicon` | `img/favicon.svg` | Site icon. |
+| `locale` | `en` | Language of the theme's own text. Catalogs ship for `en`, `es`, `fr`, `hi`, `pt`, `ru` and `zh`. |
 | `include_sidebar` | `true` | Render the navigation sidebar. |
 | `show_footer` | `true` | Render the "Improve this page" footer. |
+| `toc` | `auto` | "On this page" outline: `auto`, `expanded`, `collapsed` or `hidden`. |
 | `color_mode` | `auto` | Initial color mode: `auto`, `light` or `dark`. |
 | `light_theme` | `light` | Primer theme used in light mode. |
 | `dark_theme` | `dark` | Primer theme used in dark mode. |
@@ -96,9 +98,15 @@ To preview the demo site:
 
 ```console
 $ pip install -e . -r requirements-docs.txt
-$ mkdocs serve
+$ mkdocs serve --watch-theme
 ```
 
+It is served at <http://127.0.0.1:8000/mkdocs-primer/> — `site_url` gives the site that path, and the dev server mounts it there.
+`--watch-theme` is what makes the loop work while editing the theme: without it MkDocs watches `docs/` and `mkdocs.yml` only, and a change under `mkdocs_primer/` never reaches the browser.
+
+VS Code users get this from `.vscode/`: **Run Task → Serve the demo site**, or `F5` for the same thing with a browser attached, at full width or under the theme's 1012px breakpoint.
+`Build every site CI builds` runs the four strict builds below in order.
+
 ### Offline build
 
 The theme can register a service worker generated by [Workbox](https://developer.chrome.com/docs/workbox/). Enable `offline: true` under `theme`, build the site, then run `workbox generateSW` against the output directory. The included configuration is a complete example:

{mkdocs_primer-0.1.2 → mkdocs_primer-0.2.0}/README.md

@@ -21,7 +21,7 @@ theme:
 - Syntax highlighting mapped onto Primer's `prettylights` variables, so code colors follow the color mode. Works with both `pymdownx.highlight` and `codehilite`.
 - Copy buttons for Pygments code blocks and an accessible back-to-top control that respects reduced-motion preferences.
 - Admonitions styled after GitHub's alerts. The `admonition` extension ships no CSS and `@primer/css` has no rule for it, so most themes render `!!! note` undecorated.
-- Sidebar navigation with unlimited nesting, prev/next links, a search results page, and a 404 page.
+- Sidebar navigation with unlimited nesting, collapsed down to the section the reader is in, plus a breadcrumb trail, prev/next links, a search results page, and a 404 page.
 - Optional Workbox-powered offline support for sites served over HTTPS.
 - "Improve this page" footer, as in the Jekyll theme, with a "Last updated" line when `mkdocs-git-revision-date-localized` is enabled.
 - Native support for the plugins that need it: `mkdocs-section-index` (section labels render as links) and `mkdocs-static-i18n` (translated pages get the right `<html lang>` and can use the header language selector). See [Plugins](https://olegshulyakov.github.io/mkdocs-primer/guide/plugins/).
@@ -32,8 +32,10 @@ theme:
 | --- | --- | --- |
 | `logo` | `null` | Image shown beside the site name, relative to `docs_dir`. |
 | `favicon` | `img/favicon.svg` | Site icon. |
+| `locale` | `en` | Language of the theme's own text. Catalogs ship for `en`, `es`, `fr`, `hi`, `pt`, `ru` and `zh`. |
 | `include_sidebar` | `true` | Render the navigation sidebar. |
 | `show_footer` | `true` | Render the "Improve this page" footer. |
+| `toc` | `auto` | "On this page" outline: `auto`, `expanded`, `collapsed` or `hidden`. |
 | `color_mode` | `auto` | Initial color mode: `auto`, `light` or `dark`. |
 | `light_theme` | `light` | Primer theme used in light mode. |
 | `dark_theme` | `dark` | Primer theme used in dark mode. |
@@ -70,9 +72,15 @@ To preview the demo site:
 
 ```console
 $ pip install -e . -r requirements-docs.txt
-$ mkdocs serve
+$ mkdocs serve --watch-theme
 ```
 
+It is served at <http://127.0.0.1:8000/mkdocs-primer/> — `site_url` gives the site that path, and the dev server mounts it there.
+`--watch-theme` is what makes the loop work while editing the theme: without it MkDocs watches `docs/` and `mkdocs.yml` only, and a change under `mkdocs_primer/` never reaches the browser.
+
+VS Code users get this from `.vscode/`: **Run Task → Serve the demo site**, or `F5` for the same thing with a browser attached, at full width or under the theme's 1012px breakpoint.
+`Build every site CI builds` runs the four strict builds below in order.
+
 ### Offline build
 
 The theme can register a service worker generated by [Workbox](https://developer.chrome.com/docs/workbox/). Enable `offline: true` under `theme`, build the site, then run `workbox generateSW` against the output directory. The included configuration is a complete example:

mkdocs_primer-0.2.0/mkdocs_primer/404.html

@@ -0,0 +1,12 @@
+{% extends "base.html" %}
+
+{% block htmltitle %}404 - {{ config.site_name }}{% endblock %}
+
+{% block content %}
+  <h1>404</h1>
+  <p>{% trans %}Sorry, this page could not be found.{% endtrans %}</p>
+  {# See partials/header.html: `nav` is not locale-safe in a static template. #}
+  <p><a href="{{ base_url }}">{% trans %}Back to the home page{% endtrans %}</a></p>
+{% endblock %}
+
+{% block pagination %}{% endblock %}

{mkdocs_primer-0.1.2 → mkdocs_primer-0.2.0}/mkdocs_primer/base.html

@@ -109,6 +109,12 @@
     #}
     <script>
       (function () {
+        // Marks the document as scriptable before anything is painted, so the
+        // stylesheet can collapse what js/nav-sections.js is about to take
+        // charge of. Without this the reader would watch the navigation fold
+        // itself up a moment after the page appeared.
+        document.documentElement.classList.add('primer-js')
+
         try {
           var mode = localStorage.getItem('mkdocs-primer-color-mode')
           if (mode) document.documentElement.setAttribute('data-color-mode', mode)
@@ -120,42 +126,76 @@
   </head>
 
   <body>
-    <a href="#primer-content" class="sr-only primer-skip-link">Skip to content</a>
+    <a href="#primer-content" class="sr-only primer-skip-link">{% trans %}Skip to content{% endtrans %}</a>
 
     {%- block header %}
       {% include "partials/header.html" %}
     {%- endblock %}
 
-    <div class="primer-layout container-xl px-3">
+    {#
+      Suppressed in a static template on a translated site: `nav` there is the
+      last locale mkdocs-static-i18n built, so every link would point out of the
+      locale the visitor is actually in. See partials/header.html.
+    #}
+    {%- set show_sidebar = config.theme.include_sidebar and nav and (page or not config.plugins.get('i18n')) %}
+    <div class="primer-layout{{ ' primer-layout-with-sidebar' if show_sidebar }}">
       {%- block site_nav %}
-        {%- if config.theme.include_sidebar and nav %}
-          <aside class="primer-sidebar" aria-label="Site navigation">
+        {%- if show_sidebar %}
+          <aside class="primer-sidebar" aria-label="{% trans %}Site navigation{% endtrans %}">
             {% include "partials/nav.html" %}
           </aside>
         {%- endif %}
       {%- endblock %}
 
-      <main class="primer-main" id="primer-content">
-        <article class="markdown-body">
-          {%- block content %}
-            {{ page.content }}
+      <div class="primer-content">
+        {#
+          Above the columns rather than beside them, so the trail starts where
+          the page title does and shares the reading column's width.
+        #}
+        {%- block breadcrumbs %}
+          {% include "partials/breadcrumbs.html" %}
+        {%- endblock %}
+
+        <div class="primer-columns">
+          {#
+            A sibling of the article, not a child of it: on a wide window the
+            stylesheet lifts it into the third column, and where there is no room
+            for one it stays here, above the prose. See partials/toc.html.
+          #}
+          {%- block toc %}
+            {% include "partials/toc.html" %}
           {%- endblock %}
-        </article>
 
-        {%- block pagination %}
-          {% include "partials/pagination.html" %}
-        {%- endblock %}
+          {#
+            tabindex="-1" is what makes the skip link work: without it the browser
+            scrolls but leaves focus at the top of the document, so the next Tab
+            goes straight back into the header the visitor just skipped.
+          #}
+          <main class="primer-main" id="primer-content" tabindex="-1">
+            <article class="markdown-body">
+              {%- block content %}
+                {{ page.content }}
+              {%- endblock %}
+            </article>
 
-        {%- block footer %}
-          {%- if config.theme.show_footer %}
-            {% include "partials/footer.html" %}
-          {%- endif %}
-        {%- endblock %}
-      </main>
+            {%- block pagination %}
+              {% include "partials/pagination.html" %}
+            {%- endblock %}
+
+            {%- block footer %}
+              {%- if config.theme.show_footer %}
+                {% include "partials/footer.html" %}
+              {%- endif %}
+            {%- endblock %}
+          </main>
+        </div>
+      </div>
     </div>
 
     <button class="btn btn-octicon primer-back-to-top" type="button"
-            data-primer-back-to-top hidden aria-label="Back to top" title="Back to top">
+            data-primer-back-to-top hidden
+            aria-label="{% trans %}Back to top{% endtrans %}"
+            title="{% trans %}Back to top{% endtrans %}">
       {%- if config.theme.icon == 'lucide' %}
         <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m5 12 7-7 7 7"/><path d="M12 19V5"/></svg>
       {%- else %}
@@ -173,12 +213,27 @@
         be enabled.
       #}
       <script>var base_url = {{ base_url | tojson }}</script>
+      {#
+        Strings for the controls the scripts build at runtime. A .js file is
+        served as-is and never passes through Jinja, so it cannot reach the
+        translation catalog itself.
+      #}
+      <script>
+        var primer_strings = {
+          copy: {{ gettext('Copy code') | tojson }},
+          copied: {{ gettext('Code copied') | tojson }},
+          copied_announcement: {{ gettext('Code copied to clipboard') | tojson }},
+          copy_failed: {{ gettext('Could not copy code to clipboard') | tojson }}
+        }
+      </script>
       <script src="{{ 'js/color-mode.js' | url }}" defer></script>
       <script src="{{ 'js/copy-code.js' | url }}" defer></script>
       <script src="{{ 'js/back-to-top.js' | url }}" defer></script>
-      {%- if 'search' in config.plugins %}
-        <script src="{{ 'search/main.js' | url }}" defer></script>
-      {%- endif %}
+      <script src="{{ 'js/scrollable.js' | url }}" defer></script>
+      <script src="{{ 'js/nav-sections.js' | url }}" defer></script>
+      <script src="{{ 'js/toc-active.js' | url }}" defer></script>
+      {# Unconditional: the language and navigation popovers exist with or without search. #}
+      <script src="{{ 'js/disclosure.js' | url }}" defer></script>
       {%- if config.theme.offline %}
       <script>
         if ('serviceWorker' in navigator) {

{mkdocs_primer-0.1.2 → mkdocs_primer-0.2.0}/mkdocs_primer/css/pygments.css

@@ -105,6 +105,26 @@
   font-weight: var(--base-text-weight-semibold, 600);
 }
 
+/*
+ * The one place this file departs from GitHub's palette. In dark mode
+ * --color-prettylights-syntax-markup-heading is #1f6feb, which against the
+ * code background is 3.74:1 — under the 4.5:1 WCAG AA needs at this size.
+ * --fgColor-accent is the same hue two steps lighter and reaches 5.7:1.
+ * A diff hunk header (`@@ -1,3 +1,3 @@`) is the common case, and it carries
+ * the line numbers, so it has to be readable.
+ */
+[data-color-mode='dark'] :is(.highlight, .codehilite) :is(.gh, .gu) {
+  color: var(--fgColor-accent);
+}
+
+/* Same rule for `auto`, but only once the system has resolved to dark: in
+   light the vendored token is already 7.4:1 and stays GitHub-exact. */
+@media (prefers-color-scheme: dark) {
+  [data-color-mode='auto'] :is(.highlight, .codehilite) :is(.gh, .gu) {
+    color: var(--fgColor-accent);
+  }
+}
+
 :is(.highlight, .codehilite) .gt {
   color: var(--color-prettylights-syntax-meta-diff-range);
 }