{# 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. #} {%- block site_meta %} {%- set page_title = page.title if page and page.title else config.site_name %} {%- set page_description = page.meta.description if page and page.meta.description else config.site_description %} {%- if page and page.meta.description %} {%- elif config.site_description %} {%- endif %} {%- if config.site_author %} {%- endif %} {%- if page and page.canonical_url %} {%- endif %} {# Social crawlers generally do not infer a page title or description. #} {%- if page_description %} {%- endif %} {%- if page and page.canonical_url %} {%- endif %} {%- if page and page.meta.image %} {%- endif %} {%- if config.theme.favicon %} {%- 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 %} {%- 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 // — so without the second test those read " - " in a tab, a bookmark and a search result, a home page being normally titled after the site it opens. #} {% 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 %} {{- config.site_name }} {%- endblock %} {%- block styles %} {# Size/spacing/typography tokens first: Primer consumes them without fallbacks. #} {%- if config.theme.font and config.theme.font.source %} {%- endif %} {# Paper is white whichever mode the page was being read in, and the mode is an attribute on 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. #} {%- if config.theme.font and (config.theme.font.text or config.theme.font.code) %} {%- endif %} {%- for path in config.extra_css %} {%- 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. #} {%- block extrahead %}{% endblock %} {%- block header %} {% 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')) %}

{%- block site_nav %} {%- if show_sidebar %} {# A plain box: the column holds the navigation and nothing else, and the name now sits on the

inside it. As an

it was a complementary landmark wrapping a navigation landmark, and a screen reader announced the same name twice on the way in. #} {%- endif %} {%- endblock %}

{# 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 %}

{# 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. #}

{%- block content %} {{ page.content }} {%- endblock %}

{# 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 %} {%- block pagination %} {% include "partials/pagination.html" %} {%- endblock %}

{# 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. #}

{%- block toc %} {% include "partials/toc.html" %} {%- endblock %}

{# 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" %} {%- endif %} {%- endblock %} {%- 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. #} {# 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. #} {# Unconditional: the language and navigation popovers exist with or without search. #} {%- if config.theme.offline %} {%- endif %} {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} {%- endblock %}