mkdocs-sumi 0.1.0__py3-none-any.whl

mkdocs_sumi/__init__.py

@@ -0,0 +1,3 @@
+"""Sumi: a modern, local-first documentation theme for MkDocs."""
+
+__version__ = "0.1.0"

mkdocs_sumi/i18n.py

@@ -0,0 +1,192 @@
+"""Interface strings for the theme. English is the fallback for every key."""
+
+from __future__ import annotations
+
+STRINGS: dict[str, dict[str, str]] = {
+    'en': {
+        'search': 'Search',
+        'search_placeholder': 'Search docs or run a command…',
+        'search_no_results': 'No results for',
+        'search_loading': 'Loading index…',
+        'search_hint_open': 'to open',
+        'search_hint_move': 'to move',
+        'search_hint_close': 'to close',
+        'pages': 'Pages',
+        'commands': 'Commands',
+        'on_this_page': 'On this page',
+        'back_to_top': 'Back to top',
+        'previous': 'Previous',
+        'next': 'Next',
+        'edit_page': 'Edit this page',
+        'view_source': 'View source',
+        'copy_markdown': 'Copy as Markdown',
+        'copied': 'Copied',
+        'view_markdown': 'View as Markdown',
+        'open_in': 'Open in {name}',
+        'print': 'Print',
+        'page_actions': 'Page actions',
+        'copy': 'Copy',
+        'copy_code': 'Copy code',
+        'toggle_theme': 'Toggle dark mode',
+        'theme_light': 'Light',
+        'theme_dark': 'Dark',
+        'theme_auto': 'System',
+        'menu': 'Menu',
+        'close': 'Close',
+        'navigation': 'Navigation',
+        'skip_to_content': 'Skip to content',
+        'last_updated': 'Last updated',
+        'reading_time': '{n} min read',
+        'language': 'Language',
+        'version': 'Version',
+        'repository': 'Repository',
+        'keyboard_shortcuts': 'Keyboard shortcuts',
+        'shortcut_search': 'Open search and commands',
+        'shortcut_theme': 'Toggle dark mode',
+        'shortcut_prev_next': 'Previous / next page',
+        'shortcut_toc': 'Previous / next heading',
+        'shortcut_help': 'Show this help',
+        'built_with': 'Built with {mkdocs} and {sumi}',
+        'not_found_title': 'Page not found',
+        'not_found_text': 'The page you are looking for does not exist or has moved.',
+        'go_home': 'Go to the home page',
+        'blog': 'Blog',
+        'all_posts': 'All posts',
+        'tags': 'Tags',
+        'posted_on': 'Posted on',
+        'older_post': 'Older post',
+        'newer_post': 'Newer post',
+        'subscribe_rss': 'Subscribe via RSS',
+        'releases': 'Releases',
+        'latest': 'Latest',
+        'prerelease': 'Pre-release',
+        'archived': 'Archived',
+        'download': 'Download',
+        'asset': 'Asset',
+        'size': 'Size',
+        'checksum': 'SHA-256',
+        'release_notes': 'Release notes',
+        'old_version': 'You are reading the documentation for an older version.',
+        'go_latest': 'Go to the latest version',
+        'expand_all': 'Expand all',
+        'zoom_image': 'Zoom image',
+        'cmd_toggle_theme': 'Toggle light / dark',
+        'cmd_copy_markdown': 'Copy this page as Markdown',
+        'cmd_view_markdown': 'Open this page as Markdown',
+        'cmd_edit': 'Edit this page',
+        'cmd_print': 'Print this page',
+        'cmd_top': 'Scroll to top',
+        'cmd_home': 'Go to the home page',
+        'cmd_language': 'Switch language: {name}',
+        'cmd_version': 'Switch version: {name}',
+        'cmd_llms': 'Open llms.txt',
+        'whole_site': 'Whole site',
+        'print_title': 'Printable edition',
+        'contents': 'Contents',
+    },
+    'zh': {
+        'search': '搜索',
+        'search_placeholder': '搜索文档或执行命令…',
+        'search_no_results': '没有找到',
+        'search_loading': '正在加载索引…',
+        'search_hint_open': '打开',
+        'search_hint_move': '移动',
+        'search_hint_close': '关闭',
+        'pages': '页面',
+        'commands': '命令',
+        'on_this_page': '本页目录',
+        'back_to_top': '回到顶部',
+        'previous': '上一篇',
+        'next': '下一篇',
+        'edit_page': '编辑此页',
+        'view_source': '查看源码',
+        'copy_markdown': '复制为 Markdown',
+        'copied': '已复制',
+        'view_markdown': '查看 Markdown',
+        'open_in': '在 {name} 中打开',
+        'print': '打印',
+        'page_actions': '页面操作',
+        'copy': '复制',
+        'copy_code': '复制代码',
+        'toggle_theme': '切换深色模式',
+        'theme_light': '浅色',
+        'theme_dark': '深色',
+        'theme_auto': '跟随系统',
+        'menu': '菜单',
+        'close': '关闭',
+        'navigation': '导航',
+        'skip_to_content': '跳到正文',
+        'last_updated': '最后更新',
+        'reading_time': '约 {n} 分钟',
+        'language': '语言',
+        'version': '版本',
+        'repository': '代码仓库',
+        'keyboard_shortcuts': '键盘快捷键',
+        'shortcut_search': '打开搜索与命令面板',
+        'shortcut_theme': '切换深色模式',
+        'shortcut_prev_next': '上一页 / 下一页',
+        'shortcut_toc': '上一个 / 下一个标题',
+        'shortcut_help': '显示本帮助',
+        'built_with': '由 {mkdocs} 与 {sumi} 构建',
+        'not_found_title': '页面不存在',
+        'not_found_text': '你要找的页面不存在或已经移动。',
+        'go_home': '返回首页',
+        'blog': '博客',
+        'all_posts': '全部文章',
+        'tags': '标签',
+        'posted_on': '发布于',
+        'older_post': '更早的文章',
+        'newer_post': '更新的文章',
+        'subscribe_rss': '通过 RSS 订阅',
+        'releases': '版本发布',
+        'latest': '最新',
+        'prerelease': '预发布',
+        'archived': '已归档',
+        'download': '下载',
+        'asset': '文件',
+        'size': '大小',
+        'checksum': 'SHA-256',
+        'release_notes': '发布说明',
+        'old_version': '你正在阅读旧版本的文档。',
+        'go_latest': '前往最新版本',
+        'expand_all': '全部展开',
+        'zoom_image': '放大图片',
+        'cmd_toggle_theme': '切换浅色 / 深色',
+        'cmd_copy_markdown': '复制本页 Markdown',
+        'cmd_view_markdown': '以 Markdown 打开本页',
+        'cmd_edit': '编辑本页',
+        'cmd_print': '打印本页',
+        'cmd_top': '回到顶部',
+        'cmd_home': '回到首页',
+        'cmd_language': '切换语言：{name}',
+        'cmd_version': '切换版本：{name}',
+        'cmd_llms': '打开 llms.txt',
+        'whole_site': '全站',
+        'print_title': '打印版',
+        'contents': '目录',
+    },
+}
+STRINGS['zh_TW'] = {
+    **STRINGS['zh'],
+    'search': '搜尋', 'search_placeholder': '搜尋文件或執行命令…', 'on_this_page': '本頁目錄',
+    'previous': '上一篇', 'next': '下一篇', 'edit_page': '編輯此頁', 'copy_markdown': '複製為 Markdown',
+    'copied': '已複製', 'view_markdown': '檢視 Markdown', 'print': '列印', 'copy': '複製',
+    'copy_code': '複製程式碼', 'toggle_theme': '切換深色模式', 'navigation': '導覽', 'language': '語言',
+    'version': '版本', 'last_updated': '最後更新', 'keyboard_shortcuts': '鍵盤快捷鍵',
+    'not_found_title': '找不到頁面', 'blog': '部落格', 'tags': '標籤',
+}
+
+
+def translator(locale: str):
+    """Return `t(key, **kwargs)` for a locale such as `en`, `zh`, `zh_CN` or `zh-TW`."""
+    norm = (locale or 'en').replace('-', '_')
+    table = STRINGS.get(norm) or STRINGS.get(norm.split('_')[0]) or STRINGS['en']
+    if norm.lower() in ('zh_tw', 'zh_hk', 'zh_hant'):
+        table = STRINGS['zh_TW']
+    fallback = STRINGS['en']
+
+    def t(key: str, **kwargs: object) -> str:
+        text = table.get(key) or fallback.get(key) or key
+        return text.format(**kwargs) if kwargs else text
+
+    return t

mkdocs_sumi/icons.py

@@ -0,0 +1,52 @@
+"""Inline SVG icons: Lucide (ISC) for interface icons, Simple Icons (CC0) for brands."""
+
+from __future__ import annotations
+
+import functools
+import json
+from importlib import resources
+
+from markupsafe import Markup, escape
+
+
+@functools.cache
+def _lucide() -> dict[str, str]:
+    return json.loads(resources.files(__package__).joinpath('vendor/icons/lucide.json').read_text('utf-8'))
+
+
+@functools.cache
+def _brands() -> dict[str, str]:
+    return json.loads(resources.files(__package__).joinpath('vendor/icons/brands.json').read_text('utf-8'))
+
+
+def has_icon(name: str) -> bool:
+    name = name.removeprefix('lucide-')
+    if name.startswith('brand-'):
+        return name[6:] in _brands()
+    return name in _lucide()
+
+
+def icon(name: str, cls: str = '', label: str | None = None) -> Markup:
+    """Return the icon as inline SVG, or an empty string for an unknown name.
+
+    `name` is a Lucide icon name (`rocket`, `book-open`) or `brand-<slug>` for
+    a Simple Icons brand (`brand-github`).
+    """
+    name = (name or '').removeprefix('lucide-')
+    aria = f' role="img" aria-label="{escape(label)}"' if label else ' aria-hidden="true"'
+    classes = f'sumi-icon {cls}'.strip()
+    if name.startswith('brand-'):
+        path = _brands().get(name[6:])
+        if path is None:
+            return Markup('')
+        return Markup(
+            f'<svg class="{classes}" viewBox="0 0 24 24" fill="currentColor"{aria}>'
+            f'<path d="{path}"/></svg>'
+        )
+    body = _lucide().get(name)
+    if body is None:
+        return Markup('')
+    return Markup(
+        f'<svg class="{classes}" viewBox="0 0 24 24" fill="none" stroke="currentColor" '
+        f'stroke-width="2" stroke-linecap="round" stroke-linejoin="round"{aria}>{body}</svg>'
+    )

mkdocs_sumi/landing.py

@@ -0,0 +1,84 @@
+"""A Markdown version of a landing page, for its `.md` copy and `llms.txt` readers.
+
+A landing page keeps its content in front matter, so its Markdown body is
+often empty. This turns the hero and sections into headings and lists.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_TAG_RE = re.compile(r'<br\s*/?>|<[^>]+>')
+
+
+def _text(value: Any) -> str:
+    text = _TAG_RE.sub(lambda m: ' ' if m.group(0).lower().startswith('<br') else '', str(value or ''))
+    return ' '.join(text.split())
+
+
+def _link(text: str, link: Any) -> str:
+    return f'[{text}]({link})' if link else text
+
+
+def _actions(items: Any) -> list[str]:
+    return [f'- {_link(_text(a.get("text")), a.get("link"))}' for a in items or [] if isinstance(a, dict) and a.get('text')]
+
+
+def _code(code: Any) -> list[str]:
+    if not isinstance(code, dict) or not code.get('content'):
+        return []
+    body = str(code['content']).rstrip('\n')
+    fence = '`' * max(3, max((len(m) for m in re.findall(r'`+', body)), default=0) + 1)
+    title = f' title="{code["title"]}"' if code.get('title') else ''
+    return [f'{fence}{code.get("lang") or "text"}{title}', body, fence, '']
+
+
+def landing_markdown(meta: dict[str, Any], body: str, h1: str | None) -> str:
+    """`h1` is the page's own heading; without one, MkDocs adds the page title."""
+    hero = meta.get('hero') or {}
+    out: list[str] = [f'# {h1}', ''] if h1 else []
+    if hero.get('title') and _text(hero['title']) != h1:
+        out += [f'**{_text(hero["title"])}**', '']
+    if hero.get('text'):
+        out += [f'> {_text(hero["text"])}', '']
+    if hero.get('install'):
+        out += ['```sh', str(hero['install']), '```', '']
+    out += _code(hero.get('code'))
+    if hero.get('actions'):
+        out += [*_actions(hero['actions']), '']
+    for s in meta.get('sections') or []:
+        if not isinstance(s, dict):
+            continue
+        kind = s.get('type') or 'content'
+        if kind == 'content':
+            if body.strip():
+                out += [body.strip(), '']
+            continue
+        if s.get('title'):
+            out += [f'## {_text(s["title"])}', '']
+        if s.get('text'):
+            out += [_text(s['text']), '']
+        items = s.get('items') or []
+        if kind == 'features':
+            for f in items:
+                name = _link(f'**{_text(f.get("title"))}**', f.get('link'))
+                out.append(f'- {name}: {_text(f.get("text"))}')
+            out.append('')
+        elif kind == 'stats':
+            out += [f'- **{_text(st.get("value"))}** {_text(st.get("label"))}' for st in items] + ['']
+        elif kind == 'steps':
+            out += [f'{n}. **{_text(st.get("title"))}**: {_text(st.get("text"))}' for n, st in enumerate(items, 1)] + ['']
+        elif kind == 'faq':
+            for f in items:
+                out += [f'### {_text(f.get("q"))}', '', str(f.get('a') or '').strip(), '']
+        elif kind == 'split':
+            out += [f'- {_text(b)}' for b in s.get('bullets') or []] + ([''] if s.get('bullets') else [])
+            out += _code(s.get('code'))
+            if s.get('markdown'):
+                out += [str(s['markdown']).strip(), '']
+        if s.get('actions'):
+            out += [*_actions(s['actions']), '']
+    if not any((s or {}).get('type', 'content') == 'content' for s in meta.get('sections') or []) and body.strip():
+        out += [body.strip(), '']
+    return '\n'.join(out).strip() + '\n'

mkdocs_sumi/markdown/attrs.py

@@ -0,0 +1,47 @@
+"""Parse `{...}` attribute lines such as `{.steps}` or `{.fields meta="type default"}`."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# A line that holds nothing but an attribute list.
+ATTR_LINE_RE = re.compile(r'^\{:?\s*((?:[.#][\w-]+|[\w-]+=(?:"[^"]*"|\'[^\']*\'|[^\s}]+))(?:\s+(?:[.#][\w-]+|[\w-]+=(?:"[^"]*"|\'[^\']*\'|[^\s}]+)))*)\s*\}\s*$')
+
+_TOKEN_RE = re.compile(r'([.#][\w-]+)|([\w-]+)=("[^"]*"|\'[^\']*\'|[^\s}]+)')
+
+
+@dataclass
+class Attrs:
+    id: str | None = None
+    classes: list[str] = field(default_factory=list)
+    values: dict[str, str] = field(default_factory=dict)
+
+    def has(self, cls: str) -> bool:
+        return cls in self.classes
+
+
+def parse_attrs(text: str) -> Attrs:
+    """Parse the inside of an attribute list (without the braces)."""
+    attrs = Attrs()
+    for m in _TOKEN_RE.finditer(text):
+        if m.group(1):
+            token = m.group(1)
+            if token[0] == '.':
+                attrs.classes.append(token[1:])
+            else:
+                attrs.id = token[1:]
+        else:
+            value = m.group(3)
+            if value[:1] in ('"', "'"):
+                value = value[1:-1]
+            attrs.values[m.group(2)] = value
+    return attrs
+
+
+def match_attr_line(text: str) -> Attrs | None:
+    """Return the parsed attributes if `text` is a lone attribute list."""
+    m = ATTR_LINE_RE.match(text.strip())
+    if not m:
+        return None
+    return parse_attrs(m.group(1))