mkdocs-primer 0.4.0__tar.gz → 0.4.2__tar.gz

mkdocs_primer-0.4.2/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+
+node_modules/
+
+site/
+
+/.agents/TODO.md
+/.agents/LOOP.md

{mkdocs_primer-0.4.0 → mkdocs_primer-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mkdocs-primer
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Documentation
 Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.9
-Requires-Dist: mkdocs>=1.6
+Requires-Dist: mkdocs<2,>=1.6
 Requires-Dist: pygments>=2.16
 Description-Content-Type: text/markdown
 
@@ -61,6 +61,7 @@ theme:
 | `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. |
+| `nav_expand` | `all` | Navigation sections to render with their pages: `all`, or `active` to render only the section holding the current page and sections without their own page. Use `active` on large sites to cut page size and build time. |
 | `show_footer` | `true` | Render the footer bar. |
 | `show_footer_generator` | `true` | Show "Made with mkdocs-primer and MkDocs" in the footer. |
 | `social` | `[]` | Icon links shown in the footer. |
@@ -105,7 +106,7 @@ CI fails if those committed files drift from the pinned versions.
 To preview the demo site:
 
 ```console
-$ pip install -e . -r requirements-docs.txt
+$ pip install -e . --group docs   # pip 25.1+, or `uv sync`
 $ mkdocs serve --watch-theme
 ```
 

{mkdocs_primer-0.4.0 → mkdocs_primer-0.4.2}/README.md

@@ -35,6 +35,7 @@ theme:
 | `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. |
+| `nav_expand` | `all` | Navigation sections to render with their pages: `all`, or `active` to render only the section holding the current page and sections without their own page. Use `active` on large sites to cut page size and build time. |
 | `show_footer` | `true` | Render the footer bar. |
 | `show_footer_generator` | `true` | Show "Made with mkdocs-primer and MkDocs" in the footer. |
 | `social` | `[]` | Icon links shown in the footer. |
@@ -79,7 +80,7 @@ CI fails if those committed files drift from the pinned versions.
 To preview the demo site:
 
 ```console
-$ pip install -e . -r requirements-docs.txt
+$ pip install -e . --group docs   # pip 25.1+, or `uv sync`
 $ mkdocs serve --watch-theme
 ```
 

{mkdocs_primer-0.4.0 → mkdocs_primer-0.4.2}/mkdocs_primer/404.html

@@ -5,7 +5,6 @@
 {% 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 %}
 

{mkdocs_primer-0.4.0 → mkdocs_primer-0.4.2}/mkdocs_primer/base.html

@@ -1,16 +1,4 @@
 <!DOCTYPE html>
-{#
-  The three data-* attributes are all required: @primer/primitives scopes each
-  theme with selectors like
-    [data-color-mode="auto"][data-light-theme="light"]
-  so setting data-color-mode alone leaves every variable undefined.
-#}
-{#
-  `i18n_page_locale` is put on the page context by mkdocs-static-i18n. That
-  plugin only rewrites `theme.locale` for the themes it ships support for, so a
-  third-party theme that reads `theme.locale` alone labels every translated
-  page as the default language.
-#}
 <html lang="{{ i18n_page_locale | default(config.theme.locale, true) }}"
       dir="{{ config.theme.direction }}"
       data-color-mode="{{ config.theme.color_mode }}"
@@ -34,7 +22,6 @@
       {%- if page and page.canonical_url %}
         <link rel="canonical" href="{{ page.canonical_url }}">
       {%- endif %}
-      {# Social crawlers generally do not infer a page title or description. #}
       <meta property="og:type" content="website">
       <meta property="og:site_name" content="{{ config.site_name }}">
       <meta property="og:title" content="{{ page_title }}">
@@ -54,11 +41,6 @@
       {%- if config.theme.favicon %}
         <link rel="icon" href="{{ config.theme.favicon | url }}">
       {%- endif %}
-      {#
-        mkdocs-rss-plugin writes the feeds but leaves discovery to the theme,
-        so without these a reader has no way to find them. The filenames are a
-        plugin option, hence reading them back off the plugin config.
-      #}
       {%- set rss_plugin = config.plugins.get('rss') %}
       {%- if rss_plugin %}
         <link rel="alternate" type="application/rss+xml"
@@ -70,13 +52,6 @@
       {%- endif %}
     {%- endblock %}
 
-    {#
-      `page.is_homepage` is true of one page on the site: the one at the root.
-      A translated site has a home page per language, and mkdocs-static-i18n
-      puts every one but the default's under /<locale>/ — so without the second
-      test those read "<site name> - <site name>" in a tab, a bookmark and a
-      search result, a home page being normally titled after the site it opens.
-    #}
     <title>{% block htmltitle %}
       {%- set locale_home = i18n_page_locale is defined and page and page.url in [i18n_page_locale ~ '/', i18n_page_locale ~ '/index.html'] %}
       {%- if page and page.title and not page.is_homepage and not locale_home %}{{ page.title }} - {% endif %}
@@ -84,20 +59,12 @@
     {%- endblock %}</title>
 
     {%- block styles %}
-      {# Size/spacing/typography tokens first: Primer consumes them without fallbacks. #}
       {%- if config.theme.font and config.theme.font.source %}
         <link rel="stylesheet" href="{{ config.theme.font.source | url }}">
       {%- endif %}
       <link rel="stylesheet" href="{{ 'css/vendor/primitives-base.css' | url }}">
       <link rel="stylesheet" href="{{ 'css/vendor/primitives-light.css' | url }}">
       <link rel="stylesheet" href="{{ 'css/vendor/primitives-dark.css' | url }}">
-      {#
-        Paper is white whichever mode the page was being read in, and the mode
-        is an attribute on <html> that the print stylesheet inherits along with
-        every dark token it selects. This hands back the light value of each
-        token the two themes disagree on. The file scopes itself to `print`;
-        the attribute here only tells the browser it can wait for it.
-      #}
       <link rel="stylesheet" media="print" href="{{ 'css/vendor/primitives-print.css' | url }}">
       <link rel="stylesheet" href="{{ 'css/vendor/primer-core.css' | url }}">
       <link rel="stylesheet" href="{{ 'css/vendor/primer-markdown.css' | url }}">
@@ -122,10 +89,6 @@
       {%- endfor %}
     {%- endblock %}
 
-    {#
-      Applies the stored color mode before first paint. Must stay inline and
-      blocking, otherwise a dark-mode visitor gets a flash of the light theme.
-    #}
     <script>
       (function () {
         // Marks the document as scriptable before anything is painted, so the
@@ -151,42 +114,22 @@
       {% include "partials/header.html" %}
     {%- endblock %}
 
-    {#
-      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 show_sidebar %}
-          {#
-            A plain box: the column holds the navigation and nothing else, and
-            the name now sits on the <nav> inside it. As an <aside> it was a
-            complementary landmark wrapping a navigation landmark, and a screen
-            reader announced the same name twice on the way in.
-          #}
-          <div class="primer-sidebar">
+          <div class="primer-sidebar" id="primer-sidebar">
             {% include "partials/nav.html" %}
           </div>
         {%- endif %}
       {%- endblock %}
 
       <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">
-          {#
-            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 %}
@@ -194,17 +137,6 @@
               {%- endblock %}
             </article>
 
-            {#
-              Page facts belong to the reading column, under the title they
-              describe. The title comes from the Markdown, inside page.content,
-              where a template cannot reach -- so this is rendered after the
-              article and its own script lifts it into place while the parser is
-              still running. After the article rather than before it for the same
-              reason the outline is: the title has to exist by the time that
-              script runs. A reader with no scripts gets the facts here instead,
-              below the prose and above the pagination, which reads as the page
-              footnote it then is.
-            #}
             {%- block metadata %}
               {% include "partials/metadata.html" %}
             {%- endblock %}
@@ -214,18 +146,6 @@
             {%- endblock %}
           </main>
 
-          {#
-            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, beside the prose in source order and above it
-            on screen. See partials/toc.html.
-
-            After the article rather than before it, so that the script inside
-            partials/toc.html can put the outline where it belongs while the
-            parser is still working -- the page title it goes under has to exist
-            by then, and nothing has been painted yet. `order` in the stylesheet
-            is what keeps it above the prose for a reader whose scripts never run.
-          #}
           <div class="primer-rail">
             {%- block toc %}
               {% include "partials/toc.html" %}
@@ -235,11 +155,6 @@
       </div>
     </div>
 
-    {#
-      Outside .primer-layout, so the bar runs the full width of the window under
-      navigation, article and outline alike -- it belongs to the site, not to
-      the reading column. Same placement .primer-header has at the other end.
-    #}
     {%- block footer %}
       {%- if config.theme.show_footer %}
         {% include "partials/footer.html" %}
@@ -261,43 +176,15 @@
     </button>
 
     {%- block scripts %}
-      {#
-        Unconditional: the search plugin is not the only consumer. Anything
-        added through `extra_javascript` reads it too — mike's version selector
-        is one — and those scripts have no way to know whether search happens to
-        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.
 
-        `theme.icon` is here for the same reason: the copy button is built by a
-        script, and every other control in the theme picks its icon set in a
-        template. The set's glyphs stay in the .js file, where they are fetched
-        once, rather than being inlined into every page that has a code block.
-      #}
       <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 }},
-          {#
-            mike's version selector, which is not part of this package but
-            reaches the page through the same header. It shows a version number
-            and carries no visible label, so this string is the only name it
-            has. See mkdocs_primer_mike/js/version-select.js.
-          #}
           version_select: {{ gettext('Select documentation version') | tojson }},
-          {#
-            The colour-mode control cycles three modes through one button, and
-            the mode it is showing has to reach its accessible name. Named in
-            the script rather than here: the mode this template knows is the one
-            the site configured, which the inline script in <head> may already
-            have replaced with the visitor's stored choice.
-          #}
           color_mode_label: {{ gettext('Change color mode (%(mode)s)') | tojson }},
           color_mode_auto: {{ gettext('Automatic') | tojson }},
           color_mode_light: {{ gettext('Light') | tojson }},
@@ -312,7 +199,6 @@
       <script src="{{ 'js/nav-sections.js' | url }}" defer></script>
       <script src="{{ 'js/toc-active.js' | url }}" defer></script>
       <script src="{{ 'js/header-title.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>

{mkdocs_primer-0.4.0 → mkdocs_primer-0.4.2}/mkdocs_primer/css/pygments.css

@@ -1,16 +1,4 @@
-/*
- * Pygments tokens mapped onto Primer's --color-prettylights-syntax-* variables.
- *
- * Those variables are defined in both the light and dark primitives, so this
- * single file gives GitHub's exact syntax colors in either color mode — there
- * is no separate dark stylesheet to keep in sync.
- *
- * Both wrappers are covered because which one appears depends on the user's
- * markdown_extensions: `.highlight` (pymdownx.highlight, fenced_code) and
- * `.codehilite` (codehilite).
- */
-
-/* Primer styles `.markdown-body .highlight pre` already; match it for codehilite. */
+
 .markdown-body .codehilite {
   margin-bottom: var(--base-size-16);
 }
@@ -27,39 +15,32 @@
   border-radius: 6px;
 }
 
-/* Highlighted line (pymdownx `hl_lines`). */
 :is(.highlight, .codehilite) .hll {
   background-color: var(--bgColor-attention-muted);
 }
 
-/* Line numbers. */
 :is(.highlight, .codehilite) :is(.lineno, .linenos, .gl) {
   color: var(--fgColor-muted);
   user-select: none;
 }
 
-/* Comments. */
 :is(.highlight, .codehilite) :is(.c, .ch, .cd, .cm, .cp, .cpf, .c1, .cs, .gp) {
   color: var(--color-prettylights-syntax-comment);
 }
 
-/* Keywords. */
 :is(.highlight, .codehilite) :is(.k, .kd, .kp, .kr, .kt) {
   color: var(--color-prettylights-syntax-keyword);
 }
 
-/* Imports and other storage modifiers. */
 :is(.highlight, .codehilite) .kn {
   color: var(--color-prettylights-syntax-storage-modifier-import);
 }
 
-/* Constants: numbers, booleans, builtins, symbols. */
 :is(.highlight, .codehilite)
   :is(.kc, .m, .mb, .mf, .mh, .mi, .il, .mo, .nb, .bp, .no, .ni, .na, .ss, .o, .ow) {
   color: var(--color-prettylights-syntax-constant);
 }
 
-/* Strings. */
 :is(.highlight, .codehilite) :is(.s, .sa, .sb, .sc, .dl, .sd, .s2, .se, .sh, .si, .sx, .s1) {
   color: var(--color-prettylights-syntax-string);
 }
@@ -68,28 +49,23 @@
   color: var(--color-prettylights-syntax-string-regexp);
 }
 
-/* Entities: function, class, decorator and exception names. */
 :is(.highlight, .codehilite) :is(.nf, .fm, .nc, .nd, .ne) {
   color: var(--color-prettylights-syntax-entity);
 }
 
-/* Markup tags (HTML/XML). */
 :is(.highlight, .codehilite) .nt {
   color: var(--color-prettylights-syntax-entity-tag);
 }
 
-/* Variables and namespaces. */
 :is(.highlight, .codehilite) :is(.nv, .vc, .vg, .vi, .vm, .nn, .nl) {
   color: var(--color-prettylights-syntax-variable);
 }
 
-/* Errors. */
 :is(.highlight, .codehilite) :is(.err, .gr) {
   color: var(--color-prettylights-syntax-invalid-illegal-text);
   background-color: var(--color-prettylights-syntax-invalid-illegal-bg);
 }
 
-/* Diff output. */
 :is(.highlight, .codehilite) .gd {
   color: var(--color-prettylights-syntax-markup-deleted-text);
   background-color: var(--color-prettylights-syntax-markup-deleted-bg);
@@ -105,20 +81,10 @@
   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);
@@ -129,7 +95,6 @@
   color: var(--color-prettylights-syntax-meta-diff-range);
 }
 
-/* Emphasis in markup lexers. */
 :is(.highlight, .codehilite) .ge {
   color: var(--color-prettylights-syntax-markup-italic);
   font-style: italic;