mkdocs 1.6.1__tar.gz → 2.0.dev0__tar.gz

mkdocs-2.0.dev0/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Documentation
+on:
+  push:
+    branches:
+        - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - run: mkdocs build
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

mkdocs-2.0.dev0/.github/workflows/test-suite.yml

@@ -0,0 +1,36 @@
+---
+name: Test Suite
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  tests:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: "ubuntu-latest"
+
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+      - uses: "actions/checkout@v4"
+      - uses: "actions/setup-python@v6"
+        with:
+          python-version: "${{ matrix.python-version }}"
+      - name: "Install dependencies"
+        run: "scripts/install"
+      - name: "Run tests"
+        run: "scripts/test"
+
+      # - name: "Run linting checks"
+      #   run: "scripts/check"
+      # - name: "Build package & docs"
+      #   run: "scripts/build"
+      # - name: "Run tests"
+      #   run: "scripts/test"
+      # - name: "Enforce coverage"
+      #   run: "scripts/coverage"

mkdocs-2.0.dev0/.gitignore

@@ -0,0 +1,4 @@
+*.pyc
+venv/
+dist/
+site/

mkdocs-2.0.dev0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: mkdocs
+Version: 2.0.dev0
+Summary: HTTP, for Python.
+Author-email: Kim Christie <noreply@lovelydinosaur.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: httpx>=1.0.dev5
+Requires-Dist: jinja2
+Requires-Dist: markdown
+Requires-Dist: pygments

mkdocs-2.0.dev0/README.md

@@ -0,0 +1,74 @@
+# MkDocs
+
+MkDocs is a smart, simple, website design tool.
+
+![MkDocs](docs/img/mkdocs.png)
+
+<br/>
+
+## Installation
+
+Install the `mkdocs` command line tool...
+
+```shell
+$ pip install git+https://github.com/encode/mkdocs.git
+```
+
+*This will install the version 2.0 pre-release.*
+
+<br/>
+
+## Getting started
+
+1. Create a `README.md` page.
+2. Run `mkdocs serve` to view your documentation in a browser.
+3. Run `mkdocs build` to build a static website ready to host.
+
+*MkDocs supports [GitHub Flavored Markdown](docs/writing.md) for page authoring.*
+
+<br/>
+
+## Writing your docs
+
+1. Create additional markdown pages.
+2. Use [markdown interlinking](docs/navigation.md#interlinking) between pages.
+3. Create a `mkdocs.toml` file to define [the site navigation](docs/navigation.md#navigation) and other configuration.
+4. Move your markdown pages into a `docs` directory, and update the config.
+
+An example `mkdocs.toml`...
+
+```toml
+[mkdocs]
+nav = [
+    {path="README.md", title="Introduction"},
+    {path="CREDITS.md", title="Credits"},
+]
+
+[loaders]
+theme = "pkg://mkdocs/default"
+docs = "dir://docs"
+
+[context]
+title = "Documentation"
+favicon = "📘"
+```
+
+*Use either [`README.md` or `index.md`](docs/navigation.md#url-structure) for the homepage.*
+
+<br/>
+
+## Custom styling
+
+Styling adaptations can be kept simple, such as customising the colour scheme, or more comprehensive, such as creating an entirely new theme.
+
+1. Configure the base theme for your project.
+2. Modify [the HTML templating](docs/styling.md#templates) to customise the layout.
+3. Override or add [CSS and JavaScript](docs/styling.md#statics) static assets.
+
+Take a look at the [default theme](https://github.com/lovelydinosaur/mkdocs-theme) and the [kelp theme](https://github.com/lovelydinosaur/kelp-theme) for examples of getting started with theming.
+
+<br/>
+
+![Kelp](docs/img/kelp.png)
+
+*The MkDocs documentation, served with the Kelp theme.*

mkdocs-2.0.dev0/docs/index.md

@@ -0,0 +1,60 @@
+# MkDocs
+
+MkDocs is a smart, simple, website design tool.
+
+![MkDocs](img/mkdocs.png)
+
+## Installation
+
+Install the `mkdocs` command line tool...
+
+```shell
+$ pip install git+https://github.com/encode/mkdocs.git
+```
+
+*This will install the version 2.0 pre-release.*
+
+## Getting started
+
+1. Create a `README.md` page.
+2. Run `mkdocs serve` to view your documentation in a browser.
+3. Run `mkdocs build` to build a static website ready to host.
+
+*MkDocs supports [GitHub Flavored Markdown](writing.md) for page authoring.*
+
+## Writing your docs
+
+1. Create additional markdown pages.
+2. Use [markdown interlinking](navigation.md#interlinking) between pages.
+3. Create a `mkdocs.toml` file to define [the site navigation](navigation.md#navigation) and other configuration.
+4. Move your markdown pages into a `docs` directory, and update the config.
+
+An example `mkdocs.toml`...
+
+```toml
+[mkdocs]
+nav = [
+    {path="README.md", title="Introduction"},
+    {path="CREDITS.md", title="Credits"},
+]
+
+[loaders]
+theme = "pkg://mkdocs/default"
+docs = "dir://docs"
+
+[context]
+title = "Documentation"
+favicon = "📘"
+```
+
+*Use either [`README.md` or `index.md`](navigation.md#url-structure) for the homepage.*
+
+## Custom styling
+
+Styling adaptations can be kept simple, such as customising the colour scheme, or more comprehensive, such as creating an entirely new theme.
+
+1. Configure the base theme for your project.
+2. Modify [the HTML templating](styling.md#templates) to customise the layout.
+3. Override or add [CSS and JavaScript](styling.md#statics) static assets.
+
+Take a look at the [default theme](https://github.com/lovelydinosaur/mkdocs-theme) and the [kelp theme](https://github.com/lovelydinosaur/kelp-theme) for examples of getting started with theming.

mkdocs-2.0.dev0/docs/navigation.md

@@ -0,0 +1,92 @@
+# Interlinking & Navigation
+
+Navigation within your documentation is handled by using [document interlinking](#interlinking), and optional [site-wide navigation](#navigation).
+
+## Interlinking
+
+Use relative markdown links to allow users to navigate between documents.
+
+For example, a website with `README.md` and `CONTRIBUTING.md` pages, might include the following…
+
+```markdown
+See our [contribution documentation](CONTRIBUTING.md) for more details on getting involved.
+```
+
+If your site includes pages within a directory structure, the page interlinking might also include [relative paths between directories](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links).
+
+## Navigation
+
+You can include site-wide navigation by using the `mkdocs.toml` configuration.
+
+This is typically used by the HTML styling to include a navigation menu.
+
+```toml
+[mkdocs]
+nav = [
+    {title="Introduction", path="index.md"},
+    {title="Writing Markdown", path="markdown.md"},
+    {title="Site Navigation", path="navigation.md"},
+    {title="HTML Styling", path="styling.md"}
+]
+```
+
+This allows the theme to display navigation controls, as well as including `← previous` and `next →` links.
+
+The navigation configuration can also include nested elements.
+
+```toml
+[mkdocs]
+nav = [
+    {title="Introduction", path="index.md"},
+    {title="Tutorial", children=[
+        {title="Creating a project", path="tutorial/new.md"},
+        {title="Adding pages", path="tutorial/pages.md"},
+        {title="Publishing your work", path="tutorial/publish.md"},
+    ]},
+    {title="Topics", children=[
+        {title="Page layouts", path="topics/layouts.md"},
+        {title="Typography", path="topics/typography.md"},
+        {title="Color schemes", path="topics/schemes.md"},
+    ]}
+]
+```
+
+## URL Structure
+
+Ensuring your website has a clean, meaningful URL structure is important for navigation.
+
+* Markdown pages are lowercased.
+* The file extension is not included in the URL.
+* Use either `index.md` or `README.md` for root URLs.
+
+**Examples**
+
+A standard documentation site...
+
+| **Markdown Page** | **HTML output**         | **URL**        |
+|-------------------|-------------------------|----------------|
+| `index.md`        | `index.html`            | `/`            |
+| `markdown.md`     | `markdown/index.html`   | `/markdown/`   |
+| `navigation.md`   | `navigation/index.html` | `/navigation/` |
+| `styling.md`      | `styling/index.html`    | `/styling/`    |
+
+<br/>
+
+Uppercase filenames and GitHub style document paths...
+
+| **Markdown Page** | **HTML output**          | **URL**        |
+|-------------------|--------------------------|----------------|
+| `README.md`       | `index.html`             | `/`            |
+| `ABOUT.md`        | `about.html`             | `/about/`      |
+
+<br/>
+
+Documentation structure including subdirectories...
+
+| **Markdown Page**        | **HTML output**                  | **URL**                 |
+|--------------------------|----------------------------------|-------------------------|
+| `index.md`               | `index.html`                     | `/`                     |
+| `tutorial/quickstart.md` | `tutorial/quickstart/index.html` | `/tutorial/quickstart/` |
+| `tutorial/next-steps.md` | `tutorial/next-steps/index.html` | `/tutorial/next-steps/` |
+
+<br/>

mkdocs-2.0.dev0/docs/styling.md

@@ -0,0 +1,153 @@
+# Themes & Styling
+
+Styling is handled with HTML templating and regular web design.
+
+The build is made up of various web resources...
+
+* [Templates](#templates) - *The HTML templates used to render documentation pages.*
+* [Pages](#pages) - *The markdown files comprising the documentation.*
+* [Statics](#statics) - *Media assests including images, CSS, and JavaScript.*
+
+Resources are loaded either from a *theme* or from the *project documentation*. The theme system allows minor local styling overrides, or complete site customisation.
+
+* [Themes](#themes) - *Theme and documentation configuration is handled in the `mkdocs.toml` file.*
+
+## Templates
+
+Anything in the `/templates/` directory is treated as a [Jinja template](https://jinja.palletsprojects.com/en/stable/templates/), and is used to render markdown pages. You can override templates locally and adapt them to make layout changes.
+
+The base template for rendering markdown pages is **`templates/base.html`**. 
+
+```html
+<html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>{{ nav.current.title or page.title }}{{ " - " ~ config.context.title if config.context.title }}</title>
+        <link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;{{ config.mkdocs.favicon or '📘' }}&lt;/text&gt;&lt;/svg&gt;">
+        <link rel="stylesheet" href="{{ '/css/highlightjs.min.css' | url }}">
+        <link rel="stylesheet" href="{{ '/css/highlightjs-copy.min.css' | url }}">
+        <link rel="stylesheet" href="{{ '/css/theme.css' | url }}">
+        <script src="{{ '/js/highlightjs.min.js' | url }}"></script>
+        <script src="{{ '/js/highlightjs-copy.min.js' | url }}"></script>
+        <script src="{{ '/js/theme.js' | url }}"></script>
+    </head>
+    <body>
+        <nav class="left">
+            {{ nav.html }}
+        </nav>
+        <nav class="right">
+            {{ page.toc }}
+        </nav>
+        <main>
+            {{ page.html }}
+            {% if nav.previous or nav.next %}
+            <div class="pagination">
+                {% if nav.previous %}
+                <a class="previous" href="{{ nav.previous.url }}">← {{ nav.previous.title }}</a>
+                {% endif %}
+                {% if nav.next %}
+                <a class="next" href="{{ nav.next.url }}">{{ nav.next.title }} →</a>
+                {% endif %}
+            </div>
+            {% endif %}
+        </main>
+    </body>
+</html>
+```
+
+The following template is included in [the default theme](https://github.com/encode/mkdocs/blob/main/src/mkdocs/theme/)...
+
+* `templates/base.html`- The base template used for rendering markdown pages.
+
+The following context is passed to the template rendering...
+
+
+*Variable*           | *Description*
+---------------------|--------------------------------------
+`page`               | The markdown page.
+`page.html`          | The page contents, rendered as HTML.
+`page.text`          | The text of the page, as markdown.
+`page.path`          | The path of the source file.
+`page.url`           | The URL from which the page is served.
+`page.toc`           | The table of contents for the page, as HTML.
+`page.title`         | The first heading in the table of contents.
+`nav`                | The site navigation.
+`nav.html`           | The site navigation, rendered into HTML.
+`nav.previous`       | The previous page, as configured in the nav.
+`nav.previous.title` | The title of the previous page.
+`nav.previous.url`   | The url of the previous page.
+`nav.next`           | The next page, as configured in the nav.
+`nav.next.title`     | The title of the next page.
+`nav.next.url`       | The url of the next page.
+`config`             | The `mkdocs.toml` configuration.
+
+## Pages
+
+Any files ending with the `*.md` extension are treated as markdown pages, and rendered into HTML, then included in the base template.
+
+The following are treated as index pages...
+
+* `README.md` - Served as `/`.
+* `index.md` - Served as `/`.
+
+All other pages are lowercased, and served from a URL without the markdown extension...
+
+* `CONTRIBUTING.md` - Served as `/contributing/`.
+
+## Statics
+
+Any files that are not Markdown pages `*.md`, or templates `/templates/*`, are treated as static media and are included in the website without modification.
+
+This can include images, stylesheets, javascript, fonts, video and audio.
+
+The default theme includes the following static media...
+
+* [`css/theme.css`](css/theme.css)
+* [`css/highlightjs.min.css`](css/highlightjs.min.css)
+* [`css/highlightjs-copy.min.css`](css/highlightjs-copy.min.css)
+* [`js/theme.js`](js/theme.js)
+* [`js/highlightjs.min.js`](js/highlightjs.min.js)
+* [`js/highlightjs-copy.min.js`](js/highlightjs-copy.min.js)
+
+## Themes
+
+Themes can be packaged and distributed as part of a zip archive. The archive can the either be loaded remotely from a URL, or downloaded and included locally.
+
+Controlling how resources are loaded for the theme and documentation is handled with the `mkdocs.toml` config file.
+
+**Example configurations**
+
+*The default theme supplied by the `mkdocs` package, and the documentation served directly from the project directory. This is the default configuration...*
+
+```toml
+[loaders]
+theme = "pkg://mkdocs/default"
+docs = "dir://"
+```
+
+*The default theme as a `.zip` URL, and a local `docs` directory...*
+
+```toml
+[loaders]
+theme = "https://github.com/lovelydinosaur/mkdocs-theme/archive/refs/heads/main.zip"
+docs = "dir://docs"
+```
+
+*A theme downloaded locally, and a `docs` directory...*
+
+```toml
+[loaders]
+theme = "dir://theme"
+docs = "dir://docs"
+```
+
+*Both the theme and the documentation included in a single directory...*
+
+```toml
+[mkdocs]
+theme = "dir://docs"
+docs = "dir://docs"
+```
+
+<br/>