PyPI - mkdocs - Versions diffs - 2.0.dev3__tar.gz → 2.0.dev5__tar.gz - Mend

mkdocs 2.0.dev3tar.gz → 2.0.dev5tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (339) hide show

mkdocs-2.0.dev5/PKG-INFO ADDED Viewed

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: mkdocs
+Version: 2.0.dev5
+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.dev6
+Requires-Dist: jinja2
+Requires-Dist: markdown
+Description-Content-Type: text/markdown
+# MkDocs
+MkDocs is a smart, simple, website design tool.
+## Installation
+To install MkDocs, run the following command from the command line:
+```shell
+pip install mkdocs --pre
+```
+This will install the version 2.0 pre-release.
+## Getting started
+1. Create a `docs/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.
+## Writing your docs
+1. Create additional markdown pages.
+2. Use relative interlinking between pages.
+3. Include images and use relative interlinking from pages.
+*MkDocs supports [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for page authoring.*
+## Styling your docs
+1. Create a `templates/base.html` to customise the styling.
+2. Include css and javascript to serve static files.
+*MkDocs uses [Jinja templating](https://jinja.palletsprojects.com/en/stable/templates/) for HTML rendering.*
+A starting point can be as simple as...
+```html
+<html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>{{ page.toc.title }}</title>
+        <link rel="stylesheet" href="{{ '/css/default.css' | url }}">
+    </head>
+    <body>
+        <main>
+            {{ page.html }}
+        </main>
+    </body>
+</html>
+```

mkdocs-2.0.dev5/docs/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,11 @@
+## 2.0.dev5
+**Navigation Support Bugfix**
+Use relative URLs for site navigation. Ensures that sites hosted on a subpath still link correctly. [#54](https://github.com/encode/mkdocs/pull/54), [#55](https://github.com/encode/mkdocs/pull/55)
+## 2.0.dev4
+**Navigation Support**
+Preliminary support for site navigation. [#49](https://github.com/encode/mkdocs/pull/49)

mkdocs-2.0.dev5/docs/LICENSE.md ADDED Viewed

@@ -0,0 +1,9 @@
+Copyright © 2026, Encode OSS Ltd.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+<p align="center">&mdash; 💖 &mdash;</p>

{mkdocs-2.0.dev3 → mkdocs-2.0.dev5}/docs/README.md RENAMED Viewed

@@ -2,13 +2,15 @@
 MkDocs is a smart, simple, website design tool.
-Getting started is easy...
+## Installation
+To install MkDocs, run the following command from the command line:
 ```shell
-$ pip install mkdocs --pre
+pip install mkdocs --pre
 ```
-*This will install the version 2.0 pre-release.*
+This will install the version 2.0 pre-release.
 ## Getting started

{mkdocs-2.0.dev3/themes/default → mkdocs-2.0.dev5/docs}/css/theme.css RENAMED Viewed

@@ -27,55 +27,34 @@
 /* Layout... */
-nav.left {
-    position: fixed;
-    width : 20%;
-    padding: 2rem 1rem 1rem 2rem;
-    height: 100%;
-    overflow-y: scroll;
-}
 main {
-    margin-left: 20%;
+    margin: 0 auto 0 auto;
     width: 60%;
     padding: 1rem;
 }
-nav.right {
-    position: fixed;
-    margin-left: 80%;
-    width : 20%;
-    padding: 2rem 2rem 1rem 1rem;
-    height: 100%;
-    overflow-y: scroll;
-}
 @media (max-width: 1000px) {
     main {
         padding: 1.5rem 1rem;
         width: 75%;
-        margin-left: 25%;
-    }
-    nav.left {
-        padding: 2rem 1rem 1rem 2rem;
-        width: 25%;
-        position: fixed;
     }
-    nav.right {
+    nav.toc {
         display: none;
     }
 }
-@media (max-width: 800px) {
+@media (max-width: 750px) {
     main {
         padding: 1.5rem 1rem;
         width: 100%;
-        margin-left: 0;
     }
-    nav.left {
+    nav.toc {
         display: none;
     }
-    nav.right {
+    nav.site {
         display: none;
     }
 }
@@ -91,20 +70,31 @@ body {
     color: var(--fg-color);
     background-color: var(--bg-color);
     font-family: Helvetica, sans-serif;
+    --border-color: linear-gradient(to right, #ffafc7 10%, #73d7ee 10% 20%, #613915 20% 30%, #000000 30% 40%, #e50000 40% 50%, #ff8d00 50% 60%, #ffee00 60% 70%, #028121 70% 80%, #004cff 80% 90%, #760088 90%);
+    border-top: 0.5em solid;
+    border-bottom: 0.5em solid;
+    border-image: var(--border-color) 1;
 }
-h1, h2 {
-    border-bottom: 1px solid var(--neutral-color);
-    padding-bottom: 0.3rem;
-}
 h1, h2, h3, h4, h5 {
     margin-top: 1.5rem;
     margin-bottom: 1.5rem;
     line-height: 1.3;
 }
-h1 { font-size: 2rem; }
-h2 { font-size: 1.5rem; margin-top: 3.5rem; }
+h1 {
+    font-family: courier;
+    text-align: center;
+    font-size: 3.5rem;
+    border-top: 1px solid var(--neutral-color);
+    border-bottom: 1px solid var(--neutral-color);
+}
+h2 {
+    border-bottom: 1px solid var(--neutral-color);
+    padding-bottom: 0.3rem;
+    font-size: 1.5rem;
+    margin-top: 3.5rem;
+}
 h3 { font-size: 1.25rem; }
 h4 { font-size: 1rem; }
@@ -117,12 +107,11 @@ strong {
 }
 ul, ol {
-    margin-bottom: 1.5rem;
     padding-left: 2rem;
 }
 li {
-    margin-bottom: 0.5rem;
+    margin: 0.5rem 0;
 }
 hr {
@@ -152,6 +141,14 @@ pre code {
     color: var(--code-bg-color);
 }
+h1 a {
+    color: inherit;
+}
+h1 a:hover {
+    text-decoration: none;
+}
 a {
     color: var(--link-color);
     text-decoration: none;
@@ -179,7 +176,7 @@ a.toclink {
     text-decoration: none;
 }
-a.toclink:hover::after {
+h2 a.toclink:hover::after {
     content: "#";
     margin: 0 0.8rem;
     color: var(--neutral-color);
@@ -203,55 +200,101 @@ a.toclink:hover::after {
 .admonition.warning   .admonition-title { color: var(--accent-warning); }
 .admonition.caution   .admonition-title { color: var(--accent-caution); }
+/* Pagination styling */
+div.pagination {
+    height: 1.5rem;
+    border-top: 3px solid var(--neutral-color);
+    padding: 1rem 0;
+}
+div.pagination a.previous {
+    float: left;
+    text-decoration: none;
+}
+div.pagination a.next {
+    float: right;
+    text-decoration: none;
+}
 /* Navigation styling */
-nav ul {
+nav.site {
+    position: fixed;
+    width : 20%;
+    padding: 2rem;
+    height: 100%;
+    overflow-y: scroll;
+}
+nav.site ul {
     padding: 0;
     margin: 0;
 }
-nav li {
+nav.site li {
     padding: 0;
     margin: 0.5rem 0;
     display: block;
 }
-nav li a {
-    color: var(--fg-color);
-}
-nav li a.active {
+nav.site li a.active {
     color: var(--link-color);
 }
-nav li a:hover {
+nav.site li a:hover {
     color: var(--link-color);
     text-decoration: none;
 }
-nav.right li a {
+nav.site li a {
     color: var(--muted-fg-color);
 }
-nav.right li a:hover {
+nav.site li a:hover {
     color: var(--fg-color);
     text-decoration: none;
 }
-/* Pagination styling */
+/* Table of contents styling */
-div.pagination {
-    height: 1.5rem;
-    border-top: 3px solid var(--neutral-color);
-    padding: 1rem 0;
+nav.toc {
+    position: fixed;
+    margin-left: 80%;
+    width : 20%;
+    padding: 2rem;
+    height: 100%;
+    overflow-y: scroll;
 }
-div.pagination a.previous {
-    float: left;
+nav.toc ul {
+    padding: 0;
+    margin: 0;
+}
+nav.toc li {
+    padding: 0;
+    margin: 0.5rem 0;
+    display: block;
+}
+nav.toc li a.active {
+    color: var(--link-color);
+}
+nav.toc li a:hover {
+    color: var(--link-color);
     text-decoration: none;
 }
-div.pagination a.next {
-    float: right;
+nav.toc li a {
+    color: var(--muted-fg-color);
+}
+nav.toc li a:hover {
+    color: var(--fg-color);
     text-decoration: none;
 }
+/* Navigation styling */

{mkdocs-2.0.dev3/themes/default → mkdocs-2.0.dev5/docs}/templates/base.html RENAMED Viewed

@@ -2,8 +2,8 @@
     <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.context.favicon or '📘' }}&lt;/text&gt;&lt;/svg&gt;">
+        <title>{{ page.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;🦋&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 }}">
@@ -12,24 +12,14 @@
         <script src="{{ '/js/theme.js' | url }}"></script>
     </head>
     <body>
-        <nav class="left">
-            {{ nav.html }}
+        <nav class="site">
+            {% include "navigation.html" %}
         </nav>
-        <nav class="right">
-            {{ page.toc }}
+        <nav class="toc">
+            {{ page.toc.html }}
         </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>

mkdocs-2.0.dev5/docs/templates/navigation.html ADDED Viewed

@@ -0,0 +1,3 @@
+<ul>
+    {% for item in nav %}<li><a href="{{ item.page.url | url }}"{% if item.page.url == page.url %} class="active"{% endif %}>{{ item.title }}</a></li>{% endfor %}
+</ul>

{mkdocs-2.0.dev3 → mkdocs-2.0.dev5}/pyproject.toml RENAMED Viewed

@@ -5,6 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "mkdocs"
 description = "HTTP, for Python."
+readme = "docs/README.md"
 requires-python = ">=3.10"
 authors = [
     { name = "Kim Christie", email = "noreply@lovelydinosaur.com" },
@@ -22,7 +23,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-    "httpx>=1.0.dev5",
+    "httpx>=1.0.dev6",
     "click",
     "jinja2",
     "markdown",

mkdocs-2.0.dev5/src/mkdocs/__version__.py ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ __title__ = "mkdocs"
2	+ __version__ = "2.0.dev5"

{mkdocs-2.0.dev3 → mkdocs-2.0.dev5}/src/mkdocs/extensions/relative_urls.py RENAMED Viewed

@@ -34,15 +34,13 @@ class URLProcessor(markdown.treeprocessors.Treeprocessor):
                     path_from = page.path
                     path_to = os.path.normpath(path_from.parent.joinpath(url.path))
-                    target = site.lookup.get(path_to)
+                    target = site.lookup_by_path(path_to)
                     if target is None:
                         continue  # Broken link!
                     url_from = page.url
                     url_to = target.url
-                    rewrite = posixpath.relpath(url_to, url_from)
-                    if url_to.endswith('/') and rewrite != '.':
-                        rewrite += '/'
+                    rewrite = mkdocs.link_to(url_from, url_to)
                     if url.query:
                         rewrite += f'?{url.query}'
                     if url.fragment:

{mkdocs-2.0.dev3 → mkdocs-2.0.dev5}/src/mkdocs/mkdocs.py RENAMED Viewed

@@ -20,7 +20,7 @@ RESET = '\033[0m'
 # The build context is used to ensure the current page and the site index
 # are available to the RelativeURLs markdown extension.
 _current_page = contextvars.ContextVar('current_page')
-_site_index = contextvars.ContextVar('site_index')
+_site = contextvars.ContextVar('site')
 def get_current_page():
@@ -31,12 +31,24 @@ def get_current_page():
 def get_site():
-    ctx = _site_index.get()
+    ctx = _site.get()
     if ctx is None:
         raise RuntimeError("No current context")
     return ctx
+def link_to(path_from, path_to):
+    if path_from == path_to:
+        return '.'
+    p0 = path_from.split('/')
+    p1 = path_to.split('/')
+    for idx, pair in enumerate(zip(p0, p1)):
+        if pair[0] != pair[1]:
+            break
+    p = ['..' for i in p0[idx+1:]] + p1[idx:]
+    return '/'.join(p)
 class Page:
     def __init__(self, path):
         self.path = path
@@ -64,13 +76,19 @@ class Site:
         self._pages = pages
         self._statics = statics
-        self.lookup = {
+        self._paths = {
             str(resource.path): resource for resource in pages + statics
         }
-        self.lookup_by_url = {
+        self._urls = {
             str(resource.url): resource for resource in pages + statics
         }
+    def lookup_by_path(self, path) -> Page | Static | None:
+        return self._paths.get(path)
+    def lookup_by_url(self, url) -> Page | Static | None:
+        return self._urls.get(url)
     @property
     def pages(self) -> list[Page]:
         return list(self._pages)
@@ -93,6 +111,26 @@ class TableOfContents:
         return bool(self._items)
+class NavItem:
+    def __init__(self, title: str, page: Page):
+        self.title = title
+        self.page = page
+class Navigation:
+    def __init__(self, nav_items):
+        self._items = nav_items
+    def __iter__(self):
+        return iter(self._items)
+    @property
+    def html(self):
+        page = get_current_page()
+        t = jinja2.Template("""<ul>{% for item in nav %}<li><a href="{{ item.page.url }}"  {% if item.page == page %}class="active"{% endif %}>{{ item.title }}</a></li>{% endfor %}</ul>""")
+        return t.render({"nav": self, "page": page})
 class PageContext:
     def __init__(self, page, text, html, toc):
         self.path = page.path
@@ -110,7 +148,8 @@ class PageContext:
 class MkDocs:
     def __init__(self, input_dir):
-        self.site_index = self.load_site(input_dir)
+        self.site = self.load_site(input_dir)
+        self.nav = self.load_nav({}, self.site)
         self.env = self.init_env(input_dir)
         self.md = self.init_md()
         self.base = self.env.get_template('base.html')
@@ -140,12 +179,34 @@ class MkDocs:
         statics = sorted(statics, key=lambda x: x.url)
         return Site(pages, statics)
+    def load_nav(self, config, site):
+        if not config:
+            config = {"nav": [
+                {"title": page.path.stem, "path": str(page.path)}
+                for page in site.pages
+            ]}
+        nav_config = config.get('nav', [])
+        nav_config = nav_config if isinstance(nav_config, list) else []
+        nav_items = []
+        for item in nav_config:
+            if not isinstance(item, dict):
+                continue
+            path = item.get('path', '')
+            title = item.get('title', '')
+            if not path:
+                continue
+            if path:
+                page = site.lookup_by_path(path)
+            nav_item = NavItem(title, page)
+            nav_items.append(nav_item)
+        return Navigation(nav_items)
     def init_env(self, input_dir) -> jinja2.Environment:
         @jinja2.pass_context
         def url(ctx, url_to):
             url_from = ctx['page'].url
-            url_rel = posixpath.relpath(url_to, url_from)  # This isn't correct
-            return url_rel
+            return link_to(url_from, url_to)
         dir = pathlib.Path(input_dir)
         loader = jinja2.ChoiceLoader([
@@ -178,19 +239,21 @@ class MkDocs:
     @contextlib.contextmanager
     def set_context(self, current_page):
         token_page = _current_page.set(current_page)
-        token_site = _site_index.set(self.site_index)
+        token_site = _site.set(self.site)
         try:
             yield
         finally:
             _current_page.reset(token_page)
-            _site_index.reset(token_site)
+            _site.reset(token_site)
+    # Commands...
     def build(self, input, output):
         input_dir = pathlib.Path(input)
         output_dir = pathlib.Path(output)
-        print(DARK_GRAY + "Collected %d resources" % len(self.site_index) + RESET)
-        for page in self.site_index.pages:
+        print(DARK_GRAY + "Collected %d resources" % len(self.site) + RESET)
+        for page in self.site.pages:
             print(GREEN + " + " + RESET + BOLD + str(page.path) + RESET + DARK_GRAY + " [markdown]" + RESET)
             input_path = input_dir.joinpath(page.path)
             output_path = output_dir.joinpath(page.build_path)
@@ -200,12 +263,12 @@ class MkDocs:
                 html = self.md.reset().convert(text)
                 toc = TableOfContents(self.md)
                 page_ctx = PageContext(page=page, text=text, html=html, toc=toc)
-                output = self.base.render(page=page_ctx)
+                output = self.base.render(page=page_ctx, nav=self.nav)
             output_path.parent.mkdir(parents=True, exist_ok=True)
             output_path.write_text(output)
-        for static in self.site_index.statics:
+        for static in self.site.statics:
             print(GREEN + " + " + RESET + BOLD + str(static.path) + RESET + DARK_GRAY + " [static]" + RESET)
             input_path = input_dir.joinpath(static.path)
             output_path = output_dir.joinpath(static.path)
@@ -216,15 +279,15 @@ class MkDocs:
     def serve(self, input):
         input_dir = pathlib.Path(input)
-        print(DARK_GRAY + "Serving %d resources" % len(self.site_index) + RESET)
-        for page in self.site_index.pages:
+        print(DARK_GRAY + "Serving %d resources" % len(self.site) + RESET)
+        for page in self.site.pages:
             print(GREEN + " + " + RESET + BOLD + str(page.url) + RESET + DARK_GRAY + " [markdown]" + RESET)
-        for static in self.site_index.statics:
+        for static in self.site.statics:
             print(GREEN + " + " + RESET + BOLD + str(static.url) + RESET + DARK_GRAY + " [static]" + RESET)
         print()
         def app(request):
-            resource = self.site_index.lookup_by_url.get(request.url.path)
+            resource = self.site.lookup_by_url(request.url.path)
             if isinstance(resource, Page):
                 input_path = input_dir.joinpath(resource.path)
@@ -233,7 +296,7 @@ class MkDocs:
                     html = self.md.reset().convert(text)
                     toc = TableOfContents(self.md)
                     page_ctx = PageContext(page=resource, text=text, html=html, toc=toc)
-                    output = self.base.render(page=page_ctx)
+                    output = self.base.render(page=page_ctx, nav=self.nav)
                 return httpx.Response(200, content=httpx.HTML(output))
             elif isinstance(resource, Static):
                 input_path = input_dir.joinpath(resource.path)
@@ -244,6 +307,8 @@ class MkDocs:
         server.serve()
+# Command line client...
 @click.group()
 def cli():
     if pathlib.Path('mkdocs.yml').exists():

mkdocs 2.0.dev3__tar.gz → 2.0.dev5__tar.gz

mkdocs 2.0.dev3tar.gz → 2.0.dev5tar.gz