mkdocs 2.0.dev3__py3-none-any.whl → 2.0.dev5__py3-none-any.whl

mkdocs/__version__.py

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

mkdocs/extensions/relative_urls.py

@@ -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/mkdocs.py

@@ -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/theme/base.html

@@ -43,19 +43,33 @@ main {
 
 @media (max-width: 1000px) {
     main {
+        margin-left: 20%;
         width: 75%;
     }
 
     nav.toc {
         display: none;
     }
+
+    nav.site {
+        width: 25%;
+    }
 }
 
-@media (max-width: 600px) {
+@media (max-width: 750px) {
     main {
+        margin-left: 0;
         width: 100%;
         padding: 1rem 1.5rem;
     }
+
+    nav.toc {
+        display: none;
+    }
+
+    nav.site {
+        display: none;
+    }
 }
 
 /* Typography & spacing */
@@ -168,6 +182,14 @@ a.toclink:hover::after {
 
 /* Table of contents styling */
 
+nav.site {
+    position: fixed;
+    width : 20%;
+    padding: 2rem;
+    height: 100%;
+    overflow-y: scroll;
+}
+
 nav.toc {
     position: fixed;
     margin-left: 80%;
@@ -179,6 +201,35 @@ nav.toc {
 
 /* Navigation styling */
 
+nav.site ul {
+    padding: 0;
+    margin: 0;
+}
+
+nav.site li {
+    padding: 0;
+    margin: 0.5rem 0;
+    display: block;
+}
+
+nav.site li a.active {
+    color: var(--link-color);
+}
+
+nav.site li a:hover {
+    color: var(--link-color);
+    text-decoration: none;
+}
+
+nav.site li a {
+    color: var(--muted-fg-color);
+}
+
+nav.site li a:hover {
+    color: var(--fg-color);
+    text-decoration: none;
+}
+
 nav.toc ul {
     padding: 0;
     margin: 0;
@@ -210,6 +261,11 @@ nav.toc li a:hover {
         </style>
     </head>
     <body>
+        {% if nav %}
+        <nav class="site">
+            {% include "navigation.html" %}
+        </nav>
+        {% endif %}
         {% if page.toc %}
         <nav class="toc">
             {{ page.toc.html }}

mkdocs/theme/navigation.html

@@ -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.dev5.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+mkdocs/__init__.py,sha256=NwNA-Nxju0I4e1-Msqo_ewJLRcjJjEMiVs2bbfzoMCg,283
+mkdocs/__version__.py,sha256=wk6npcQOpkv95xsvTaNoOpDNXZLjJ10qrE-tday-4e4,46
+mkdocs/mkdocs.py,sha256=Lv_LVrZCLaznNfP9R_0CKS3ALVxuBok9Q_xWTux3PXM,10484
+mkdocs/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs/extensions/relative_urls.py,sha256=AS-d1CraHrAFT83RZlpJE8T4cL-CH8h5KC-pwNdd7G4,1848
+mkdocs/extensions/short_codes.py,sha256=I2SwGMcG9OT_vpkJwPI8cHBTkwQAjSPZmoQKfctsHn4,950
+mkdocs/extensions/strike_thru.py,sha256=GrCbfMrHz_2Vlh3E572EQYOSDzEGym34pkHElzF2HZY,577
+mkdocs/theme/base.html,sha256=mioyexMGSzSLbjxINKd-V1Go5UqyhALVfqtkQ2n8UrQ,4286
+mkdocs/theme/navigation.html,sha256=BI5tAPZva9MrAVcuUOBlTJi_Xn1XyBq_2-y69Bdkabw,174
+mkdocs-2.0.dev5.dist-info/METADATA,sha256=RQhYo24CafCop9w3eojiL30avsbipnF9m0Ly9SVAQS8,2205
+mkdocs-2.0.dev5.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mkdocs-2.0.dev5.dist-info/entry_points.txt,sha256=5PqBrzYJLZ9-yQ0djvENWOQ-0x6Xj30JYNSzM_m70ZU,38
+mkdocs-2.0.dev5.dist-info/RECORD,,

mkdocs-2.0.dev3.dist-info/METADATA

@@ -1,20 +0,0 @@
-Metadata-Version: 2.5
-Name: mkdocs
-Version: 2.0.dev3
-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

mkdocs-2.0.dev3.dist-info/RECORD

@@ -1,12 +0,0 @@
-mkdocs/__init__.py,sha256=NwNA-Nxju0I4e1-Msqo_ewJLRcjJjEMiVs2bbfzoMCg,283
-mkdocs/__version__.py,sha256=y7OAtBTvz302kS_lnppuG9xWGpwIuMUpU4-ayC_CP8A,46
-mkdocs/mkdocs.py,sha256=RnJ8wj2vzozAEqD-X5JMxRoP2wi-uWBC8NH7_DF1Slg,8677
-mkdocs/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocs/extensions/relative_urls.py,sha256=woA0EUuCXa10wt6C0VCjYnY7jO-fj-wd9uOVU20D96U,1950
-mkdocs/extensions/short_codes.py,sha256=I2SwGMcG9OT_vpkJwPI8cHBTkwQAjSPZmoQKfctsHn4,950
-mkdocs/extensions/strike_thru.py,sha256=GrCbfMrHz_2Vlh3E572EQYOSDzEGym34pkHElzF2HZY,577
-mkdocs/theme/base.html,sha256=xB9VAAgy6zwucGedwTfdhigwNu_lhY3OKiY4aSsN6ZQ,3471
-mkdocs-2.0.dev3.dist-info/METADATA,sha256=KerzpRlQfNrRd1Ocu8w5tpEkXPdEyPNgGWyYJwpfzdU,729
-mkdocs-2.0.dev3.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-mkdocs-2.0.dev3.dist-info/entry_points.txt,sha256=5PqBrzYJLZ9-yQ0djvENWOQ-0x6Xj30JYNSzM_m70ZU,38
-mkdocs-2.0.dev3.dist-info/RECORD,,