Copy basic template and styling for documentation from uv (#729)

This copies the documentation scaffolding from uv, doing the minimum
amount of work to make it viable.

---------

Co-authored-by: David Peter <sharkdp@users.noreply.github.com>

CONTRIBUTING.md

@@ -99,6 +99,39 @@ git -C ruff reset --hard $(git ls-tree main -- ruff | awk '{print $3}')
 git add ruff
 ```
 
+## Documentation
+
+To preview any changes to the documentation locally run the development server with:
+
+```shell
+# For contributors.
+uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.public.yml
+
+# For members of the Astral org, which has access to MkDocs Insiders via sponsorship.
+uvx --with-requirements docs/requirements-insiders.txt -- mkdocs serve -f mkdocs.insiders.yml
+```
+
+The documentation should then be available locally at
+[http://127.0.0.1:8000/ty/](http://127.0.0.1:8000/ty/).
+
+To update the documentation dependencies, edit `docs/requirements.in` and
+`docs/requirements-insiders.in`, then run:
+
+```shell
+uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12
+uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12
+```
+
+Documentation is deployed automatically on release by publishing to the
+[Astral documentation](https://github.com/astral-sh/docs) repository, which itself deploys via
+Cloudflare Pages.
+
+After making changes to the documentation, format the markdown files with:
+
+```shell
+npx prettier --prose-wrap always --write "**/*.md"
+```
+
 ## Releasing ty
 
 Releases can only be performed by Astral team members.

docs/.overrides/main.html

@@ -0,0 +1,34 @@
+{% extends "base.html" %}
+
+{% block htmltitle %}
+{% if page.meta and page.meta.title %}
+<title>{{ page.meta.title }} | {{ config.site_name }}</title>
+{% elif page.title and not page.is_homepage %}
+<title>{{ page.title | striptags }} | {{ config.site_name }}</title>
+{% else %}
+<title>{{ config.site_name }}</title>
+{% endif %}
+{% endblock %}
+
+{% block extrahead %}
+<link rel="apple-touch-icon" sizes="180x180" href="https://docs.astral.sh/static/apple-touch-icon.png"/>
+<link rel="icon" type="image/png" sizes="32x32" href="https://docs.astral.sh/static/favicon-32x32.png"/>
+<link rel="icon" type="image/png" sizes="16x16" href="https://docs.astral.sh/static/favicon-16x16.png"/>
+<link rel="manifest" href="https://docs.astral.sh/static/site.webmanifest"/>
+<link rel="mask-icon" href="https://docs.astral.sh/static/safari-pinned-tab.svg" color="#2e183d"/>
+<meta name="msapplication-TileColor" content="#d7ff64"/>
+<meta name="theme-color" content="#ffffff"/>
+<meta name="robots" content="index,follow"/>
+<script type="application/ld+json">
+    {
+        {% if page and page.meta.git_revision_date_localized_raw_iso_datetime %}
+        "datePublished": "{{ page.meta.git_revision_date_localized_raw_iso_datetime }}Z",
+        "dateModified": "{{ page.meta.git_revision_date_localized_raw_iso_datetime  }}Z",
+        {% endif %}
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        "name": "Astral Docs",
+        "url": "https://docs.astral.sh"
+    }
+</script>
+{% endblock %}

docs/.overrides/partials/integrations/analytics/fathom.html

@@ -0,0 +1 @@
+<script src="https://cdn.usefathom.com/script.js" data-site="ESKBRHGN" defer></script>

docs/index.md

@@ -1,19 +1,8 @@
 # ty
 
-**[Installation](#installation)** |
-**[Module discovery](#module-discovery)** |
-**[Python version](#python-version)** |
-**[Excluding files](#excluding-files)** |
-**[Editor integration](#editor-integration)** |
-**[Rules](#rules)** |
-**[Suppressions](#suppressions)** |
-**[Configuration](#configuration)** |
-**[Exit codes](#exit-codes)** |
-**[Reference](#reference)**
-
 ## Getting started
 
-For a quick guide on getting started, see the top-level [README](../README.md#getting-started).
+For a quick guide on getting started, see the [README](https://github.com/astral-sh/ty/blob/main/README.md#getting-started).
 
 ## Installation
 
@@ -170,7 +159,7 @@ The Python version may also be explicitly specified using the
 
 ## Excluding files
 
-ty automatically discovers all Python files in your project. You can customize where ty searches by using the [`src.include`](./reference/configuration.md#include-1) and [`src.exclude`](./reference/configuration.md#exclude-1) settings.
+ty automatically discovers all Python files in your project. You can customize where ty searches by using the [`src.include`](./reference/configuration.md#include) and [`src.exclude`](./reference/configuration.md#exclude) settings.
 
 For example, with the following configuration, ty checks all Python files in the `src` and `tests` directories except those in the `src/generated` directory:
 

docs/js/extra.js

@@ -0,0 +1,90 @@
+function cleanupClipboardText(targetSelector) {
+  const targetElement = document.querySelector(targetSelector);
+
+  // exclude "Generic Prompt" and "Generic Output" spans from copy
+  const excludedClasses = ["gp", "go"];
+
+  const clipboardText = Array.from(targetElement.childNodes)
+    .filter(
+      (node) =>
+        !excludedClasses.some((className) =>
+          node?.classList?.contains(className)
+        )
+    )
+    .map((node) => node.textContent)
+    .filter((s) => s != "");
+  return clipboardText.join("").trim();
+}
+
+// Sets copy text to attributes lazily using an Intersection Observer.
+function setCopyText() {
+  // The `data-clipboard-text` attribute allows for customized content in the copy
+  // See: https://www.npmjs.com/package/clipboard#copy-text-from-attribute
+  const attr = "clipboardText";
+  // all "copy" buttons whose target selector is a <code> element
+  const elements = document.querySelectorAll(
+    'button[data-clipboard-target$="code"]'
+  );
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach((entry) => {
+      // target in the viewport that have not been patched
+      if (
+        entry.intersectionRatio > 0 &&
+        entry.target.dataset[attr] === undefined
+      ) {
+        entry.target.dataset[attr] = cleanupClipboardText(
+          entry.target.dataset.clipboardTarget
+        );
+      }
+    });
+  });
+
+  elements.forEach((elt) => {
+    observer.observe(elt);
+  });
+}
+
+// Using the document$ observable is particularly important if you are using instant loading since
+// it will not result in a page refresh in the browser
+// See `How to integrate with third-party JavaScript libraries` guideline:
+// https://squidfunk.github.io/mkdocs-material/customization/?h=javascript#additional-javascript
+document$.subscribe(function () {
+  setCopyText();
+});
+
+// Use client-side redirects for anchors that have moved.
+// Other redirects should use `redirect_maps` in the `mkdocs.yml` file instead.
+(function () {
+  // (there are no redirects yet)
+  let redirect_maps = {};
+
+  // The prefix for the site, see `site_dir` in `mkdocs.yml`
+  let site_dir = "ty";
+
+  function get_path() {
+    var path = window.location.pathname;
+
+    // Trim the site prefix
+    if (path.startsWith("/" + site_dir + "/")) {
+      path = path.slice(site_dir.length + 2);
+    }
+
+    // Always include a trailing `/`
+    if (!path.endsWith("/")) {
+      path = path + "/";
+    }
+
+    // Check for an anchor
+    var anchor = window.location.hash.substring(1);
+    if (!anchor) {
+      return path;
+    }
+
+    return path + "#" + anchor;
+  }
+
+  let path = get_path();
+  if (path && redirect_maps.hasOwnProperty(path)) {
+    window.location.replace("/" + site_dir + "/" + redirect_maps[path]);
+  }
+})();

docs/requirements-insiders.in

@@ -0,0 +1,2 @@
+-r requirements.in
+mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4

docs/requirements-insiders.txt

@@ -0,0 +1,154 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12
+babel==2.15.0
+    # via
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+beautifulsoup4==4.13.4
+    # via
+    #   markdownify
+    #   mkdocs-llmstxt
+black==23.10.0
+    # via -r docs/requirements.in
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   black
+    #   mkdocs
+colorama==0.4.6
+    # via
+    #   click
+    #   mkdocs
+    #   mkdocs-material
+ghp-import==2.1.0
+    # via mkdocs
+gitdb==4.0.12
+    # via gitpython
+gitpython==3.1.44
+    # via mkdocs-git-revision-date-localized-plugin
+idna==3.7
+    # via requests
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+linkify-it-py==2.0.3
+    # via markdown-it-py
+markdown==3.6
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markdown-it-py==3.0.0
+    # via
+    #   mdformat
+    #   mdformat-gfm
+    #   mdit-py-plugins
+markdownify==1.1.0
+    # via mkdocs-llmstxt
+markupsafe==2.1.5
+    # via
+    #   jinja2
+    #   mkdocs
+mdformat==0.7.22
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+    #   mdformat-tables
+    #   mkdocs-llmstxt
+mdformat-admon==2.0.2
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-mkdocs
+mdformat-gfm==0.3.6
+    # via mdformat-mkdocs
+mdformat-mkdocs==2.0.4
+    # via -r docs/requirements.in
+mdformat-tables==0.4.1
+    # via mdformat-gfm
+mdit-py-plugins==0.4.1
+    # via
+    #   mdformat-admon
+    #   mdformat-gfm
+mdurl==0.1.2
+    # via markdown-it-py
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+mkdocs==1.5.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+    #   mkdocs-redirects
+mkdocs-git-revision-date-localized-plugin==1.3.0
+    # via -r docs/requirements.in
+mkdocs-llmstxt==0.2.0
+    # via -r docs/requirements.in
+mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4
+    # via
+    #   -r docs/requirements-insiders.in
+    #   -r docs/requirements.in
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocs-redirects==1.2.2
+    # via -r docs/requirements.in
+more-itertools==10.3.0
+    # via mdformat-mkdocs
+mypy-extensions==1.0.0
+    # via black
+packaging==24.1
+    # via
+    #   black
+    #   mkdocs
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via
+    #   black
+    #   mkdocs
+platformdirs==4.2.2
+    # via
+    #   black
+    #   mkdocs
+pygments==2.18.0
+    # via mkdocs-material
+pymdown-extensions==10.8.1
+    # via mkdocs-material
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pytz==2025.1
+    # via mkdocs-git-revision-date-localized-plugin
+pyyaml==6.0.1
+    # via
+    #   mkdocs
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+regex==2022.10.31
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
+six==1.16.0
+    # via
+    #   markdownify
+    #   python-dateutil
+smmap==5.0.2
+    # via gitdb
+soupsieve==2.7
+    # via beautifulsoup4
+typing-extensions==4.14.0
+    # via beautifulsoup4
+uc-micro-py==1.0.3
+    # via linkify-it-py
+urllib3==2.2.2
+    # via requests
+watchdog==4.0.1
+    # via mkdocs

docs/requirements.in

@@ -0,0 +1,10 @@
+black>=23.10.0
+mkdocs>=1.5.0
+mkdocs-material>=9.1.18
+mkdocs-redirects>=1.2.1
+mdformat>=0.7.17
+mdformat-mkdocs>=2.0.4
+mdformat-admon>=2.0.2
+mkdocs-redirects>=1.2.2
+mkdocs-git-revision-date-localized-plugin>=1.3.0
+mkdocs-llmstxt>=0.2.0

docs/requirements.txt

@@ -0,0 +1,156 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12
+babel==2.15.0
+    # via
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+beautifulsoup4==4.13.4
+    # via
+    #   markdownify
+    #   mkdocs-llmstxt
+black==24.4.2
+    # via -r docs/requirements.in
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   black
+    #   mkdocs
+colorama==0.4.6
+    # via
+    #   click
+    #   mkdocs
+    #   mkdocs-material
+ghp-import==2.1.0
+    # via mkdocs
+gitdb==4.0.12
+    # via gitpython
+gitpython==3.1.44
+    # via mkdocs-git-revision-date-localized-plugin
+idna==3.7
+    # via requests
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+linkify-it-py==2.0.3
+    # via markdown-it-py
+markdown==3.6
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markdown-it-py==3.0.0
+    # via
+    #   mdformat
+    #   mdformat-gfm
+    #   mdit-py-plugins
+markdownify==1.1.0
+    # via mkdocs-llmstxt
+markupsafe==2.1.5
+    # via
+    #   jinja2
+    #   mkdocs
+mdformat==0.7.22
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+    #   mdformat-tables
+    #   mkdocs-llmstxt
+mdformat-admon==2.0.6
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-mkdocs
+mdformat-gfm==0.3.6
+    # via mdformat-mkdocs
+mdformat-mkdocs==3.0.0
+    # via -r docs/requirements.in
+mdformat-tables==0.4.1
+    # via mdformat-gfm
+mdit-py-plugins==0.4.1
+    # via
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+mdurl==0.1.2
+    # via markdown-it-py
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+    #   mkdocs-redirects
+mkdocs-get-deps==0.2.0
+    # via mkdocs
+mkdocs-git-revision-date-localized-plugin==1.3.0
+    # via -r docs/requirements.in
+mkdocs-llmstxt==0.2.0
+    # via -r docs/requirements.in
+mkdocs-material==9.5.29
+    # via -r docs/requirements.in
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocs-redirects==1.2.2
+    # via -r docs/requirements.in
+more-itertools==10.3.0
+    # via mdformat-mkdocs
+mypy-extensions==1.0.0
+    # via black
+packaging==24.1
+    # via
+    #   black
+    #   mkdocs
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via
+    #   black
+    #   mkdocs
+platformdirs==4.2.2
+    # via
+    #   black
+    #   mkdocs-get-deps
+pygments==2.18.0
+    # via mkdocs-material
+pymdown-extensions==10.8.1
+    # via mkdocs-material
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pytz==2025.1
+    # via mkdocs-git-revision-date-localized-plugin
+pyyaml==6.0.1
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+regex==2024.5.15
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
+six==1.16.0
+    # via
+    #   markdownify
+    #   python-dateutil
+smmap==5.0.2
+    # via gitdb
+soupsieve==2.7
+    # via beautifulsoup4
+typing-extensions==4.14.0
+    # via beautifulsoup4
+uc-micro-py==1.0.3
+    # via linkify-it-py
+urllib3==2.2.2
+    # via requests
+watchdog==4.0.1
+    # via mkdocs

docs/stylesheets/extra.css

@@ -0,0 +1,229 @@
+:root {
+  --black: #261230;
+  --white: #ffffff;
+  --radiate: #d7ff64;
+  --flare: #6340ac;
+  --rock: #78876e;
+  --galaxy: #261230;
+  --space: #30173d;
+  --comet: #6f5d6f;
+  --cosmic: #de5fe9;
+  --sun: #ffac2f;
+  --electron: #46ebe1;
+  --aurora: #46eb74;
+  --constellation: #5f6de9;
+  --neutron: #cff3cf;
+  --proton: #f6afbc;
+  --nebula: #cdcbfb;
+  --supernova: #f1aff6;
+  --starlight: #f4f4f1;
+  --lunar: #fbf2fc;
+  --asteroid: #e3cee3;
+  --crater: #f0dfdf;
+}
+
+[data-md-color-scheme="astral-light"] {
+  --md-default-bg-color--dark: var(--black);
+  --md-primary-fg-color: var(--galaxy);
+  --md-typeset-a-color: var(--flare);
+  --md-accent-fg-color: var(--cosmic);
+}
+
+[data-md-color-scheme="astral-dark"] {
+  --md-default-bg-color: var(--galaxy);
+  --md-default-fg-color: var(--white);
+  --md-default-fg-color--light: var(--white);
+  --md-default-fg-color--lighter: var(--white);
+  --md-primary-fg-color: var(--space);
+  --md-primary-bg-color: var(--white);
+  --md-accent-fg-color: var(--cosmic);
+
+  --md-typeset-color: var(--white);
+  --md-typeset-a-color: var(--radiate);
+  --md-typeset-mark-color: var(--sun);
+
+  --md-code-fg-color: var(--white);
+  --md-code-bg-color: var(--space);
+
+  --md-code-hl-comment-color: var(--asteroid);
+  --md-code-hl-punctuation-color: var(--asteroid);
+  --md-code-hl-generic-color: var(--supernova);
+  --md-code-hl-variable-color: var(--starlight);
+  --md-code-hl-string-color: var(--radiate);
+  --md-code-hl-keyword-color: var(--supernova);
+  --md-code-hl-operator-color: var(--supernova);
+  --md-code-hl-number-color: var(--electron);
+  --md-code-hl-special-color: var(--electron);
+  --md-code-hl-function-color: var(--neutron);
+  --md-code-hl-constant-color: var(--radiate);
+  --md-code-hl-name-color: var(--md-code-fg-color);
+
+  --md-typeset-del-color: hsla(6, 90%, 60%, 0.15);
+  --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15);
+
+  --md-typeset-table-color: hsla(0, 0%, 100%, 0.12);
+  --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035);
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-dark-mode-only"] {
+  display: none; /* Hide dark images in light mode */
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-light"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-light-mode-only"] {
+  display: inline; /* Show light images in light mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-light"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-light-mode-only"] {
+  display: none; /* Hide light images in dark mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-dark-mode-only"] {
+  display: inline; /* Show dark images in dark mode */
+}
+
+/* See: https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465 */
+.md-typeset__table {
+  min-width: 100%;
+}
+.md-typeset table:not([class]) {
+  display: table;
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/8519 */
+[data-md-color-scheme="astral-dark"] details summary a {
+  color: var(--flare);
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/9046 */
+[data-md-color-scheme="astral-dark"] div.admonition {
+  color: var(--md-code-fg-color);
+  background-color: var(--md-code-bg-color);
+}
+
+/* Prevent the shadow from the nav title from blurring the top link.
+The box shadow isn't really doing anything anyway.
+
+This is a consequence of the reduced nav spacing below. */
+.md-nav--primary .md-nav__title {
+  box-shadow: none;
+}
+
+/* Omits the nav title "ty" entirely unless on a small screen, in which case
+the nav title is needed for backwards navigation in the collapsible
+nav variant.
+
+See https://github.com/astral-sh/uv/issues/5130 */
+@media screen and (min-width: 76.25em) {
+  .md-nav__title {
+    display: none;
+  }
+}
+
+
+/* Always take the full screen for content, require scrolling to see the footer
+This stops the size of the nav from jumping around when you visit a page without
+a lot of content (i.e., an overview page). We don't apply this to sma screens
+because the nav is in a hamburger menu anyway
+*/
+@media screen and (min-width: 76.25em) {
+  .md-main {
+    min-height: 100vh;
+  }
+}
+
+/* Tweak the formatting of the primary nav on a large screen */
+@media screen and (min-width: 76.25em) {
+  .md-nav--primary .md-nav {
+    font-size: 0.75rem;
+  }
+  /* Remove the bold from the section headings, use a larger font instead */
+  .md-nav__item--section > .md-nav__link {
+      font-weight: normal;
+      font-size: 0.85rem;
+  }
+  /* Reducing spacing between nav items to fit more content 
+  First, disable `nav__link` spacing then use `nav__item` to enforce margins this reduces inconsistencies in the spacing. */
+  .md-nav--primary .md-nav__link {
+    margin: 0;
+  }
+  .md-nav--primary .md-nav__item {
+    margin-top: 0.35em;
+  }
+  /* Use larger spacing for the sections headings */
+  .md-nav--primary .md-nav__item--section {
+    margin-bottom: 0.75em;
+    margin-top: 1em;
+  }
+  /* Decrease the font size of items in a collapsible section */
+  .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list {
+    font-size: 0.725rem;
+  }
+  /* Increase top margin on the first item of a collapsible section */
+  .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item:first-of-type {
+    margin-top: 0.5em;
+  }
+  /* Increase bottom margin on the last item of a collapsible section */
+  .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item:last-of-type {
+    margin-bottom: 0.575em;
+  }
+  /* Increase the size of the first nav item to match the sections 
+  It has no children, so it is not considered a section */
+  .md-nav--primary > .md-nav__list > .md-nav__item:first-of-type {
+    font-size: 0.85rem;
+    margin-bottom: 0.75em; 
+  }
+}
+
+/* Bold the active nav link for accessibility */
+.md-nav__link--active {
+  font-weight: bold;
+}
+
+/* See: https://mkdocstrings.github.io/recipes/#prevent-selection-of-prompts-and-output-in-python-code-blocks */
+.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
+  user-select: none;
+}
+
+/* Styling for the generated CLI reference page */
+.cli-reference dd {
+  margin-top: 0.1em;
+  margin-bottom: 0.5em;
+}
+.cli-reference dd p {
+  margin-block-start: 0.2em;
+  margin-block-end: 0.3em;
+}
+.cli-reference ul {
+  margin-bottom: 0.1em;
+}
+h3.cli-reference {
+  font-size: 1.1em;
+  margin: 0 0 0 0;
+}
+
+/* Styling for anchor link headers */
+.toclink {
+  color: unset !important;
+}
+
+.toclink:hover {
+  color: var(--md-accent-fg-color) !important;
+}
+
+/* Omit the first breadcrumb item, which is the "Introduction" */
+.md-path__list > .md-path__item:first-of-type {
+  display: none;
+}
+.md-path__list > .md-path__item:nth-of-type(2):before {
+  display: none;
+}
+
+/* Hide the modified date — its positioning is awkward but will require theme
+modifications */
+.md-source-file__fact {
+  visibility: hidden;
+}

mkdocs.insiders.yml

@@ -0,0 +1,4 @@
+INHERIT: mkdocs.template.yml
+
+watch:
+  - mkdocs.template.yml

mkdocs.public.yml

@@ -0,0 +1,6 @@
+# NOTE: Usually, you should edit the template instead.
+# This file is used for forks and contributors, production uses `mkdocs.insiders.yml`.
+INHERIT: mkdocs.template.yml
+
+watch:
+  - mkdocs.template.yml

mkdocs.template.yml

@@ -0,0 +1,96 @@
+site_name: ty
+theme:
+  name: material
+  logo: assets/logo-letter.svg
+  favicon: assets/favicon.ico
+  features:
+    - navigation.path
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.sections
+    - navigation.indexes
+    - navigation.tracking
+    - content.code.annotate
+    - toc.follow
+    - navigation.footer
+    - navigation.top
+    - content.code.copy
+    - content.tabs.link
+  palette:
+    # Note: Using the system theme works with the insiders version
+    # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: astral-light
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: astral-dark
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  custom_dir: docs/.overrides
+repo_url: https://github.com/astral-sh/ty
+repo_name: ty
+site_author: astral-sh
+site_url: https://docs.astral.sh/ty/
+site_dir: site/ty
+site_description: ty is an extremely fast Python type checker.
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.snippets:
+  - pymdownx.magiclink:
+  - attr_list:
+  - toc:
+      anchorlink: true
+      anchorlink_class: "toclink"
+  - md_in_html:
+  - pymdownx.inlinehilite:
+  - pymdownx.superfences:
+  - markdown.extensions.attr_list:
+  - pymdownx.keys:
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
+plugins:
+  - search
+  - git-revision-date-localized:
+      timezone: UTC # It can only be in UTC unless the ISO time can include timezone.
+extra_css:
+  - stylesheets/extra.css
+extra_javascript:
+  - js/extra.js
+extra:
+  analytics:
+    provider: fathom
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/astral-sh/ty
+    - icon: fontawesome/brands/discord
+      link: https://discord.com/invite/astral-sh
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/ty/
+    - icon: fontawesome/brands/x-twitter
+      link: https://x.com/astral_sh
+nav:
+  - Overview: index.md
+  - Reference:
+      - reference/index.md
+      - Rules: reference/rules.md
+      - CLI: reference/cli.md
+      - Configuration: reference/configuration.md
+      - Editor settings: reference/editor-settings.md
+      - Environment variables: reference/env.md
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn