mkdocs-pixel-lab 0.2.0__tar.gz → 0.2.1__tar.gz

mkdocs_pixel_lab-0.2.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: mkdocs-pixel-lab
+Version: 0.2.1
+Summary: A vibrant, accessible MkDocs documentation theme by Trained-by-Humans.
+Project-URL: Homepage, https://github.com/trained-by-humans/mkdocs-pixel-lab
+Project-URL: Documentation, https://github.com/trained-by-humans/mkdocs-pixel-lab#readme
+Project-URL: Repository, https://github.com/trained-by-humans/mkdocs-pixel-lab
+Project-URL: Issues, https://github.com/trained-by-humans/mkdocs-pixel-lab/issues
+Project-URL: Changelog, https://github.com/trained-by-humans/mkdocs-pixel-lab/releases
+Author: Trained-by-Humans
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: THIRD_PARTY_LICENSES.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: MkDocs
+Classifier: License :: OSI Approved :: Apache Software License
+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
+Requires-Python: >=3.10
+Requires-Dist: mkdocs<2,>=1.6
+Requires-Dist: pygments<3,>=2.19.1
+Requires-Dist: pymdown-extensions<11,>=10
+Provides-Extra: test
+Requires-Dist: pytest-playwright>=0.7; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/pixel-lab-logo.svg" alt="Pixel Lab retro logo" width="480">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mkdocs-pixel-lab/"><img src="https://img.shields.io/pypi/v/mkdocs-pixel-lab?style=flat-square&amp;logo=pypi&amp;logoColor=white&amp;label=PyPI&amp;color=C48800" alt="Latest PyPI release"></a>
+  <a href="https://pypi.org/project/mkdocs-pixel-lab/"><img src="https://img.shields.io/badge/Python-3.10%2B-2377C8?style=flat-square&amp;logo=python&amp;logoColor=white" alt="Python 3.10 or newer"></a>
+  <a href="https://github.com/trained-by-humans/mkdocs-pixel-lab/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/mkdocs-pixel-lab?style=flat-square&amp;label=License&amp;color=287C35" alt="Apache 2.0 license"></a>
+  <a href="https://www.mkdocs.org/"><img src="https://img.shields.io/badge/MkDocs-%3E%3D1.6%2C%20%3C2-7E46B6?style=flat-square" alt="MkDocs &gt;=1.6, &lt;2"></a>
+</p>
+
+<p align="center">
+  A retro-inspired theme for <a href="https://www.mkdocs.org/">MkDocs</a>, with pixel borders, bold colors, and arcade-style shadows.<br>
+  Built for modern documentation with responsive navigation, search, and rich Markdown components.
+</p>
+
+## Preview
+
+<table>
+  <tr>
+    <td align="center"><img src="tests/snapshots/desktop.png" alt="Pixel Lab desktop documentation preview" height="480"></td>
+    <td align="center"><img src="tests/snapshots/mobile.png" alt="Pixel Lab mobile documentation preview" height="480"></td>
+  </tr>
+  <tr>
+    <td align="center">Desktop</td>
+    <td align="center">Mobile</td>
+  </tr>
+</table>
+
+## Demo
+
+Visit [Pixel Lab on GitHub Pages](https://trained-by-humans.github.io/mkdocs-pixel-lab/)
+to see the theme in action. The documentation site uses Pixel Lab itself and
+includes examples of its components.
+
+## Features
+
+- A tastefully designed, retro-inspired theme with pixel-art assets, crisp borders, and playful shadows.
+- Optional metadata, Git-based sitemap dates, and `robots.txt` plugins.
+- Opt-in Google Analytics 4 with consent controls.
+
+## Quick start
+
+For an existing MkDocs project, install Pixel Lab:
+
+```bash
+python -m pip install mkdocs-pixel-lab
+```
+
+Select it in your existing `mkdocs.yml`:
+
+```yaml
+theme:
+  name: pixel-lab
+```
+
+Preview your site:
+
+```bash
+mkdocs serve
+```
+
+Requires Python 3.10 or newer. Installing Pixel Lab also installs MkDocs,
+Pymdown Extensions, and Pygments.
+
+Starting a new project? Follow [Get started](docs/getting-started.md) for
+environment setup, a new site, and enabling Markdown extensions.
+
+## Documentation
+
+- [Theme setup](docs/setup/index.md): colors, fonts, icons, branding, navigation, search, repository links, and analytics.
+- [Components](docs/components/index.md): Markdown syntax, live examples, required extensions, and appearance settings.
+- [Reference](docs/reference/configuration.md): configuration defaults, [bundled plugins](docs/reference/plugins.md), [compatibility](docs/reference/compatibility.md), and [troubleshooting](docs/reference/troubleshooting.md).
+- [Upgrading](docs/reference/upgrading.md): migration notes and checks for existing sites.

mkdocs_pixel_lab-0.2.1/README.md

@@ -0,0 +1,74 @@
+<p align="center">
+  <img src="assets/pixel-lab-logo.svg" alt="Pixel Lab retro logo" width="480">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mkdocs-pixel-lab/"><img src="https://img.shields.io/pypi/v/mkdocs-pixel-lab?style=flat-square&amp;logo=pypi&amp;logoColor=white&amp;label=PyPI&amp;color=C48800" alt="Latest PyPI release"></a>
+  <a href="https://pypi.org/project/mkdocs-pixel-lab/"><img src="https://img.shields.io/badge/Python-3.10%2B-2377C8?style=flat-square&amp;logo=python&amp;logoColor=white" alt="Python 3.10 or newer"></a>
+  <a href="https://github.com/trained-by-humans/mkdocs-pixel-lab/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/mkdocs-pixel-lab?style=flat-square&amp;label=License&amp;color=287C35" alt="Apache 2.0 license"></a>
+  <a href="https://www.mkdocs.org/"><img src="https://img.shields.io/badge/MkDocs-%3E%3D1.6%2C%20%3C2-7E46B6?style=flat-square" alt="MkDocs &gt;=1.6, &lt;2"></a>
+</p>
+
+<p align="center">
+  A retro-inspired theme for <a href="https://www.mkdocs.org/">MkDocs</a>, with pixel borders, bold colors, and arcade-style shadows.<br>
+  Built for modern documentation with responsive navigation, search, and rich Markdown components.
+</p>
+
+## Preview
+
+<table>
+  <tr>
+    <td align="center"><img src="tests/snapshots/desktop.png" alt="Pixel Lab desktop documentation preview" height="480"></td>
+    <td align="center"><img src="tests/snapshots/mobile.png" alt="Pixel Lab mobile documentation preview" height="480"></td>
+  </tr>
+  <tr>
+    <td align="center">Desktop</td>
+    <td align="center">Mobile</td>
+  </tr>
+</table>
+
+## Demo
+
+Visit [Pixel Lab on GitHub Pages](https://trained-by-humans.github.io/mkdocs-pixel-lab/)
+to see the theme in action. The documentation site uses Pixel Lab itself and
+includes examples of its components.
+
+## Features
+
+- A tastefully designed, retro-inspired theme with pixel-art assets, crisp borders, and playful shadows.
+- Optional metadata, Git-based sitemap dates, and `robots.txt` plugins.
+- Opt-in Google Analytics 4 with consent controls.
+
+## Quick start
+
+For an existing MkDocs project, install Pixel Lab:
+
+```bash
+python -m pip install mkdocs-pixel-lab
+```
+
+Select it in your existing `mkdocs.yml`:
+
+```yaml
+theme:
+  name: pixel-lab
+```
+
+Preview your site:
+
+```bash
+mkdocs serve
+```
+
+Requires Python 3.10 or newer. Installing Pixel Lab also installs MkDocs,
+Pymdown Extensions, and Pygments.
+
+Starting a new project? Follow [Get started](docs/getting-started.md) for
+environment setup, a new site, and enabling Markdown extensions.
+
+## Documentation
+
+- [Theme setup](docs/setup/index.md): colors, fonts, icons, branding, navigation, search, repository links, and analytics.
+- [Components](docs/components/index.md): Markdown syntax, live examples, required extensions, and appearance settings.
+- [Reference](docs/reference/configuration.md): configuration defaults, [bundled plugins](docs/reference/plugins.md), [compatibility](docs/reference/compatibility.md), and [troubleshooting](docs/reference/troubleshooting.md).
+- [Upgrading](docs/reference/upgrading.md): migration notes and checks for existing sites.

mkdocs_pixel_lab-0.2.1/docs/components/admonitions.md

@@ -0,0 +1,93 @@
+# Admonitions
+
+Use admonitions for callouts with custom titles and Markdown content. For
+predefined titles and type-specific colors, use [Alerts](alerts.md).
+
+## Enable
+
+Enable Python-Markdown's admonition extension in `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - admonition
+```
+
+## Write an admonition
+
+!!! note "Before you start"
+
+    Keep the configuration in one place and merge new settings into it.
+
+```markdown
+!!! note "Before you start"
+
+    Keep the configuration in one place and merge new settings into it.
+```
+
+Indent the body four spaces. The type follows `!!!`; the quoted custom title
+is optional. For example, `!!! note` without a quoted title displays Note.
+Admonition types currently share the same theme styling.
+
+For expandable notes using `???` or `???+`, see [Collapsible content](details.md).
+
+> [!NOTE]
+>
+> Content inside an admonition shares its outer shadow. See
+> [Nest components](index.md#nest-components) for the nesting rule.
+
+## Customization
+
+These theme settings customize all admonitions. Admonitions don't use the
+type-specific `alert_*` colors:
+
+```yaml
+theme:
+  name: pixel-lab
+  highlight_color: "#f5c842"
+  surface_color: "#fffdf2"
+  border_color: "#101410"
+  shadow_color: "#101410"
+```
+
+| Parameter | Default | Effect |
+| --- | --- | --- |
+| `highlight_color` | Golden yellow · `#f5c842` | Admonition title background |
+| `surface_color` | Ivory · `#fffdf2` | Admonition body background |
+| `text_color` | Dark green-gray · `#182018` | Admonition body text |
+| `border_color` | Near-black · `#101410` | Admonition outline and title divider |
+| `shadow_color` | Near-black · `#101410` | Admonition pixel shadow |
+
+See [Common attributes](../reference/configuration.md#common-attributes).
+
+### Component-wide overrides
+
+To change every admonition's title fill, add this to your
+[custom stylesheet](index.md#load-custom-css):
+
+```css
+.admonition > .admonition-title {
+  background: #f5c842; /* Golden yellow */
+}
+```
+
+### Scoped overrides
+
+Wrap each selected admonition, following [Scope selected instances](index.md#scope-selected-instances):
+
+```markdown
+<div class="instance-admonition" markdown="1">
+
+!!! note "Before you start"
+
+    Keep the configuration in one place.
+
+</div>
+```
+
+Add the scoped rule to your stylesheet:
+
+```css
+.instance-admonition > .admonition > .admonition-title {
+  background: #f5c842; /* Golden yellow */
+}
+```

mkdocs_pixel_lab-0.2.1/docs/components/alerts.md

@@ -0,0 +1,121 @@
+# Alerts
+
+Use alerts for notes with predefined titles and semantic colors.
+Their bodies support Markdown. For a custom title, use an
+[admonition](admonitions.md) instead.
+
+## Enable
+
+Enable the extension bundled with Pixel Lab:
+
+```yaml
+markdown_extensions:
+  - mkdocs_pixel_lab.github_alerts
+```
+
+## Write an alert
+
+> [!NOTE]
+>
+> Background information that helps explain the topic.
+
+> [!TIP]
+>
+> A useful shortcut or recommendation.
+
+> [!IMPORTANT]
+>
+> Something readers should know before proceeding.
+
+> [!WARNING]
+>
+> A potential problem that needs attention.
+
+> [!CAUTION]
+>
+> A risk of damage or an irreversible action.
+
+```markdown
+> [!TIP]
+>
+> A useful shortcut or recommendation.
+```
+
+The supported types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
+
+> [!NOTE]
+>
+> Rich content inside an alert uses the alert's outer shadow rather than adding
+> its own. See [Nest components](index.md#nest-components).
+
+## Customization
+
+Each alert type has a rail/title color and a surface color. These theme
+settings customize every alert of that type:
+
+```yaml
+theme:
+  name: pixel-lab
+  alert_tip_color: "#287c35"
+  alert_tip_surface_color: "#e7f5df"
+  alert_warning_color: "#a65f00"
+  alert_warning_surface_color: "#fff0bf"
+```
+
+| Parameter | Default | Effect |
+| --- | --- | --- |
+| `alert_note_color` | Blue · `#2377c8` | Note rail and title |
+| `alert_note_surface_color` | Pale blue · `#e4f2ff` | Note background |
+| `alert_tip_color` | Dark green · `#287c35` | Tip rail and title |
+| `alert_tip_surface_color` | Pale green · `#e7f5df` | Tip background |
+| `alert_important_color` | Purple · `#6d28d9` | Important rail and title |
+| `alert_important_surface_color` | Pale lavender · `#f0e8ff` | Important background |
+| `alert_warning_color` | Amber brown · `#a65f00` | Warning rail and title |
+| `alert_warning_surface_color` | Pale yellow · `#fff0bf` | Warning background |
+| `alert_caution_color` | Dark red · `#b42318` | Caution rail and title |
+| `alert_caution_surface_color` | Pale pink · `#ffe3df` | Caution background |
+
+For the body text, outline, and shadow:
+
+| Parameter | Default | Effect |
+| --- | --- | --- |
+| `text_color` | Dark green-gray · `#182018` | Alert body text |
+| `border_color` | Near-black · `#101410` | Alert outline, except the type-specific left rail |
+| `shadow_color` | Near-black · `#101410` | Alert pixel shadow |
+
+See [Common attributes](../reference/configuration.md#common-attributes).
+
+### Component-wide overrides
+
+To customize all tip alerts, add this to your
+[custom stylesheet](index.md#load-custom-css):
+
+```css
+.gh-alert--tip {
+  --alert-color: #287c35;   /* Dark green */
+  --alert-surface: #e7f5df; /* Pale green */
+}
+```
+
+### Scoped overrides
+
+Wrap each selected alert, following [Scope selected instances](index.md#scope-selected-instances):
+
+```markdown
+<div class="instance-alert" markdown="1">
+
+> [!TIP]
+>
+> Keep the configuration in one place.
+
+</div>
+```
+
+Add the scoped rule to your stylesheet:
+
+```css
+.instance-alert > .gh-alert--tip {
+  --alert-color: #287c35;   /* Dark green */
+  --alert-surface: #e7f5df; /* Pale green */
+}
+```

mkdocs_pixel_lab-0.2.1/docs/components/code-blocks.md

@@ -0,0 +1,130 @@
+# Code blocks
+
+Fenced code supports syntax highlighting, emphasized lines, horizontal
+scrolling, and a copy button.
+
+## Enable
+
+```yaml
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.highlight
+```
+
+## Write a code block
+
+```python
+def greet(name):
+    # A small example with syntax colors.
+    return f"Hello, {name}!"
+
+print(greet("Pixel Lab"))
+```
+
+````markdown
+```python
+def greet(name):
+    # A small example with syntax colors.
+    return f"Hello, {name}!"
+
+print(greet("Pixel Lab"))
+```
+````
+
+Set the language after the opening fence. Code keeps its whitespace and
+scrolls horizontally when a line is wider than the available space.
+
+## Emphasize lines
+
+```{ .python hl_lines="2" }
+import math
+print(math.pi)
+```
+
+````markdown
+```{ .python hl_lines="2" }
+import math
+print(math.pi)
+```
+````
+
+## Copy behavior
+
+The copy button is added by the theme's JavaScript and reports success or
+failure. Without JavaScript, the code remains readable and selectable.
+Clipboard access may depend on the browser and a secure context such as
+HTTPS or localhost.
+
+## Customization
+
+These theme settings customize all code blocks:
+
+```yaml
+theme:
+  name: pixel-lab
+  code_background_color: "#101410"
+  code_text_color: "#e9f1d8"
+  code_keyword_color: "#72d572"
+  code_string_color: "#f5cf54"
+  code_function_color: "#4cc4d2"
+  code_comment_color: "#7f8978"
+  highlight_color: "#f5c842"
+```
+
+| Parameter | Default | Effect |
+| --- | --- | --- |
+| `code_background_color` | Near-black · `#101410` | Code block background |
+| `code_text_color` | Pale green · `#e9f1d8` | Default code text |
+| `code_keyword_color` | Light green · `#72d572` | Styled keyword token classes |
+| `code_string_color` | Golden yellow · `#f5cf54` | Styled string token classes |
+| `code_function_color` | Cyan · `#4cc4d2` | Function names |
+| `code_comment_color` | Gray-green · `#7f8978` | Comments |
+| `highlight_color` | Golden yellow · `#f5c842` | Emphasized-line tint and copy-button hover/focus fill |
+| `surface_color` | Ivory · `#fffdf2` | Copy-button background |
+| `strong_text_color` | Near-black · `#101410` | Copy-button text |
+| `accent_color` | Leaf green · `#4caf50` | Successful-copy button background |
+| `accent_foreground_color` | Near-black · `#101410` | Successful-copy button text |
+| `accent_dark_color` | Dark green · `#287c35` | Copy-button hover/focus outline |
+| `border_color` | Near-black · `#101410` | Block and copy-button outlines |
+| `shadow_color` | Near-black · `#101410` | Block's pixel shadow |
+
+Syntax colors apply to the Pygments token classes styled by the theme, not
+every possible token independently.
+
+Inline code has separate surface/border styling: see [Text and lists](text.md#customization).
+See [Common attributes](../reference/configuration.md#common-attributes).
+
+### Component-wide overrides
+
+To change every highlighted code block's background and text, add this to
+your [custom stylesheet](index.md#load-custom-css):
+
+```css
+.highlight {
+  --code: #101410;      /* Near-black */
+  --code-text: #e9f1d8; /* Pale green */
+}
+```
+
+### Scoped overrides
+
+Wrap each selected code block, following [Scope selected instances](index.md#scope-selected-instances):
+
+````markdown
+<div class="instance-code" markdown="1">
+
+```python
+print("Hello, Pixel Lab!")
+```
+
+</div>
+````
+
+Add the scoped rule to your stylesheet:
+
+```css
+.instance-code > .highlight {
+  --code: #101410;      /* Near-black */
+  --code-text: #e9f1d8; /* Pale green */
+}
+```

mkdocs_pixel_lab-0.2.1/docs/components/details.md

@@ -0,0 +1,119 @@
+# Collapsible content
+
+Use an expandable note for optional instructions, a longer explanation, or
+troubleshooting details.
+
+## Enable
+
+```yaml
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+```
+
+`pymdownx.details` enables the collapsible `???` syntax; `admonition` also
+enables regular `!!!` notes.
+
+For non-collapsible notes with the same styling, see [Admonitions](admonitions.md).
+
+## Closed by default
+
+??? note "Show the configuration advice"
+
+    Keep one `theme` block in `mkdocs.yml` and merge new options into it.
+
+```markdown
+??? note "Show the configuration advice"
+
+    Keep one `theme` block in `mkdocs.yml` and merge new options into it.
+```
+
+## Open by default
+
+???+ tip "Start with the defaults"
+
+    Override only the settings your site needs.
+
+```markdown
+???+ tip "Start with the defaults"
+
+    Override only the settings your site needs.
+```
+
+The browser's native `details` element handles opening and closing, including
+keyboard activation. It works without the theme's JavaScript.
+
+> [!NOTE]
+>
+> Expanded content shares the collapsible block's outer shadow. See
+> [Nest components](index.md#nest-components).
+
+## Native HTML alternative
+
+You can also write `<details>` directly. For Markdown inside the body, enable
+[`md_in_html`](index.md#scope-selected-instances) and add `markdown="1"`:
+
+```html
+<details markdown="1">
+<summary>More information</summary>
+
+This body supports **Markdown**.
+
+</details>
+```
+
+## Customization
+
+These theme settings customize all collapsible blocks. Different detail types
+currently share the same styling:
+
+```yaml
+theme:
+  name: pixel-lab
+  highlight_color: "#f5c842"
+  surface_color: "#fffdf2"
+  border_color: "#101410"
+  shadow_color: "#101410"
+```
+
+| Parameter | Default | Effect |
+| --- | --- | --- |
+| `highlight_color` | Golden yellow · `#f5c842` | Summary background |
+| `surface_color` | Ivory · `#fffdf2` | Expanded body background |
+| `border_color` | Near-black · `#101410` | Frame and summary divider |
+| `shadow_color` | Near-black · `#101410` | Outer pixel shadow |
+
+See [Common attributes](../reference/configuration.md#common-attributes).
+
+### Component-wide overrides
+
+To change every collapsible block's summary fill, add this to your
+[custom stylesheet](index.md#load-custom-css):
+
+```css
+details > summary {
+  background: #f5c842; /* Golden yellow */
+}
+```
+
+### Scoped overrides
+
+Wrap each selected block, following [Scope selected instances](index.md#scope-selected-instances):
+
+```markdown
+<div class="instance-details" markdown="1">
+
+??? note "More information"
+
+    Keep the configuration in one place.
+
+</div>
+```
+
+Add the scoped rule to your stylesheet:
+
+```css
+.instance-details > details > summary {
+  background: #f5c842; /* Golden yellow */
+}
+```