@anydigital/blades 0.27.0-alpha.16 → 0.27.0-beta.2

package/README.md

@@ -1,331 +1,163 @@
-# 🥷 Blades <sup>![](https://img.shields.io/github/v/release/anydigital/blades?label=&color=black&include_prereleases)</sup>
+# 🥷 Blades
 
 <!--section:hero-->
 
-<hgroup>Framework-agnostic,<wbr> class-light CSS+ blade kit.</hgroup>
+<hgroup>Framework-agnostic,<wbr> class-light CSS⁺ blade kit.</hgroup>
 
 <big>Use with Pico, Tailwind, or any other CSS reset/framework.</big>
 
+![](https://img.shields.io/github/v/release/anydigital/blades?label=&color=white&include_prereleases)
+[![](https://img.shields.io/github/stars/anydigital/blades?label=)](https://github.com/anydigital/blades)
+
 <!--section-->
 
 Nunjucks/Liquid batteries included (for 11ty/Build Awesome, Jekyll, etc.) 🥷
 
-<!--section:css-h2-->
-
-## CSS 'blades' <br><sub>from https://github.com/anydigital/blades</sub> <a id="blades"></a>
-
-### Install CSS
-
-Via CDN:
-
-```html
-<link href="https://cdn.jsdelivr.net/npm/@anydigital/blades@0/dist/blades.min.css" rel="stylesheet" />
-```
-
-Or import source styles via npm:
-
-```sh
-npm install @anydigital/blades
-```
-
-```css {data-caption=.css}
-@import "@anydigital/blades";
-```
+[![](https://img.shields.io/badge/Docs_&_Demos-darkslategray?style=for-the-badge)](https://blades.ninja/)
 
-<details><summary>
+---
 
-### `_base.css` styles
+<!--section:index-->
 
-</summary>
+<hgroup id="css"><small>Class-light</small>
 
-#### Overflow Control
+## [CSS blades](https://blades.ninja/css/)
 
-Prevents horizontal overflow and scrolling on the entire page:
+inspired by Pico.css
 
-```css
-html,
-body {
-  overflow-x: clip;
-}
-```
+</hgroup>
 
-This is automatically applied when you include the stylesheet.
+<!-- copy-paste of ToC from https://blades.ninja/css/ -->
+<ul class="unlist columns">
+<li><a href="https://blades.ninja/css/#table">Table</a><ul><li><a href="https://blades.ninja/css/responsive-table/">🥷 Responsive table without wrapper →</a></li>
+<li><a href="https://blades.ninja/css/#horizontal-expanders">Horizontal expanders</a></li>
+<li><a href="https://blades.ninja/css/#borderless-table">Borderless table</a></li></ul></li>
+<li><a href="https://blades.ninja/css/#content">Content</a><ul><li><a href="https://blades.ninja/css/#link-fav-icons">Link [fav]icons</a></li>
+<li><a href="https://blades.ninja/css/#heading-anchors">Heading anchors</a></li>
+<li><a href="https://blades.ninja/css/#list-markers">List markers</a></li>
+<li><a href="https://blades.ninja/css/#code">Code</a></li></ul></li>
+<li><a href="https://blades.ninja/css/#layout">Layout</a><ul><li><a href="https://blades.ninja/css/breakout/">🥷 Breakout elements →</a></li>
+<li><a href="https://blades.ninja/css/#document">Document</a></li>
+<li><a href="https://blades.ninja/css/#landmarks">Landmarks</a></li>
+<li><a href="https://blades.ninja/css/#table-of-contents">Table of contents</a></li>
+<li><a href="https://blades.ninja/css/#jump-to-top">Jump to top</a></li></ul></li>
+<li><a href="https://blades.ninja/css/#utilities">Utilities</a><ul><li><a href="https://blades.ninja/css/#auto-columns">Auto-columns</a></li>
+<li><a href="https://blades.ninja/css/#auto-dark">Auto-dark</a></li>
+<li><a href="https://blades.ninja/css/#misc">Misc</a></li></ul></li></ul>
 
-#### Full Viewport Height
+<!--section:index,install-css-->
+<details><summary role="button" class="outline"><b>Install CSS blades</b></summary>
 
-Ensures the body element takes at least the full height of the viewport using dynamic viewport height for better mobile support:
+<mark>Option A.</mark> From CDN:
 
-```css
-body {
-  min-height: 100dvh;
-}
+<!--prettier-ignore-->
+```html
+<link href="https://cdn.jsdelivr.net/npm/@anydigital/blades@^0.27.0-alpha/assets/blades.min.css" rel="stylesheet" />
+<link href="https://cdn.jsdelivr.net/npm/@anydigital/blades@^0.27.0-alpha/assets/blades.theme.min.css" rel="stylesheet" /><!-- optional -->
 ```
 
-This is automatically applied when you include the stylesheet.
-
-#### Flexbox Layout
+<mark>Option B.</mark> Via npm:
 
-Sets up a flexible column layout structure:
-
-```css
-body {
-  display: flex;
-  flex-direction: column;
-}
-
-body > main {
-  flex-grow: 1;
-}
+```sh
+npm install @anydigital/blades
 ```
 
-The body becomes a flex container with column direction, and `main` elements automatically grow to fill available space. This is useful for creating sticky footers and full-height layouts.
-
-This is automatically applied when you include the stylesheet.
-
-#### Typography Enhancements
-
-Improves text rendering and readability:
+Then import in your .css:
 
 ```css
-body {
-  hyphens: auto;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-```
-
-- Automatic hyphenation for better text flow
-- Font smoothing for cleaner text rendering across browsers
-- Hyphenation is disabled for links and tables to prevent awkward breaks
-
-This is automatically applied when you include the stylesheet.
-
-</details>
-
-<details><summary>
-
-### `_prose.css` Tailwind Typography enhancements
-
-</summary>
-
-The `.prose` class provides enhanced typography for article content and long-form text with container-like behavior:
-
-**Container:**
-
-- Full width
-- Centered with automatic inline margins
-
-**Typography Helpers:**
-
-- `sub` elements: styled for multi-line subtitles with top vertical alignment, `1.1` line height, lighter weight (`300`), and displayed as `inline-block` with `100%` width to prevent underline decoration inside links
-
-**Links:**
-
-- Custom underline offset (`0.1em`) and thickness (`1px` default, `2px` on hover)
-- Anchor links (starting with `#`) have no text decoration
-- Icon helper: `i` elements inside links are displayed as `inline-block` with normal font style to prevent underline decoration, with `1em` height and `0.25em` right margin. Nested `img` elements are styled with `100%` height, no margin, and positioned `0.15em` from the bottom for proper alignment
-
-**Headings:**
-
-- `h1` elements have a `0.5em` bottom margin
-- `h1 sub` elements get reduced font size (`50%`)
-- Support for heading anchors via `.header-anchor` class (displayed on hover to the left of the heading)
-
-**Tables:**
-
-- Tables within `.breakout` containers are automatically styled for full-bleed display and horizontal scrolling
-- Table cells (`th` and `td`) have padding of `1rem 2rem 1rem 0` (extra space on the right for better horizontal scroll on mobile) and `top` vertical alignment
-- Table headers (`th`) have `bottom` vertical alignment
-- Workaround for widening columns using hidden `hr` elements (width: `12ch`, with zero margin and hidden visibility)
-- Support for headings in Markdown tables using `big` elements (styled as bold)
-- Images in table cells have no top margin and `1em` bottom margin
-
-**Blockquotes:**
-
-- Lighter font weight (`300`)
-- Adjacent `figcaption` elements (using `+ figcaption` selector) are styled with italic text, right alignment, lighter weight (`300`), negative top margin (`-1em`), and an em dash prefix (`—`) with `0.25em` right margin
-
-**Code Blocks:**
-
-- Code blocks with `data-caption` attribute display the caption above the code block (styled with 50% opacity, italic, and `1.5em` bottom margin)
-
-</details>
-
-### `_prism.css` enhancements
-
-Includes specialized styling for Prism.js, specifically focusing on treeview components:
-
-- Custom styling for `.token.treeview-part`
-- Reduced opacity for entry lines (25%) and names (50%) to create a hierarchical visual effect
-- Entry lines have a fixed width of `2.5em`
-- Last-child entry names have no `::before` pseudo-element
-- Supports complex file tree visualizations out of the box
-
-<details><summary>
-
-### `_util.css` helpers
-
-</summary>
-
-#### Scrollbar Inversion
-
-The `.invert` class can be used to invert the scrollbar colors, which is particularly useful for dark themes or specific UI components:
-
-```css
-.invert {
-  ::-webkit-scrollbar {
-    filter: invert(1) !important;
-  }
-}
-```
-
-#### Link Whitespace Control
-
-The `.whitespace-nowrap` class can be applied to links to prevent them from wrapping, which is particularly useful when links contain icons that should stay with the text:
-
-```html
-<a href="#" class="whitespace-nowrap">
-  <i><img src="icon.svg" alt="" /></i>Stay with me
-</a>
-```
-
-This ensures the icon and the text stay together on the same line. If you need nested elements to allow wrapping, they are automatically reset to `white-space: normal`.
-
-**Usage:**
-
-```html
-<article class="prose">
-  <h1>Article Title</h1>
-  <p>Your content here...</p>
-</article>
+@import "@anydigital/blades";
+@import "@anydigital/blades.theme"; /* optional */
 ```
 
-This is automatically included when you import the stylesheet.
+Living example: https://github.com/anydigital/build-awesome-starter/blob/main/_styles/styles.css
 
 </details>
+<!--section:index-->
 
-### `breakout-css` included
+---
 
-Includes [breakout-css](https://github.com/anydigital/breakout-css) utilities for breaking out images and figures beyond their container width. Use the `.breakout` class to allow elements to extend beyond their parent container:
+<hgroup><small>Nunjucks / Liquid</small>
 
-```html
-<div class="breakout">
-  <img src="image.jpg" alt="Description" />
-</div>
-```
+## [HTML blades](https://blades.ninja/html/)
 
-The breakout container has `10%` inline padding and a max-width of `calc(10% + 65ch + 10%)`. The breakout utilities support images, pictures, figures, canvas, audio, video, tables, pre, iframe, and other media elements. Tables inside `.breakout` are specifically enhanced for horizontal scrolling and full-bleed mobile display. This is automatically included when you import the stylesheet.
+for 11ty/Build Awesome, Jekyll, etc.
 
-<!--section:njk-liquid-h2-->
+</hgroup>
 
-## Universal Template 'blades' <small>(`.njk` & `.liquid`)</small> <br><sub>from https://github.com/anydigital/blades</sub>
+- [Base HTML](https://blades.ninja/html/#base) {data-marker=🥷}
+- [Links](https://blades.ninja/html/#links)
+- [Google Tag Manager](https://blades.ninja/html/#gtm)
 
-The package includes reusable templates in the `./src/blades/` directory. These are useful for common web development patterns.
+{.columns}
 
-### Install Templates
+<!--section:index,install-html-->
+<details><summary role="button" class="outline"><b>Install HTML blades</b></summary>
 
 ```sh
 npm install @anydigital/blades
-cd ./src/_includes
-ln -s ../../node_modules/@anydigital/blades/src/blades
+cd ./_includes  # or where your includes dir is
+ln -s ../node_modules/@anydigital/blades/_includes/blades
 ```
 
-### Base HTML Template <small>(`__html.*`)</small>
-
-A unified base HTML template `blades/__html.{njk|liquid}` that provides the essential document structure with built-in support for modern web best practices.
-
-**Usage:**
+That's it! Now you can use HTML blades in your templates like this:
 
-```jinja2 {data-caption="in .njk layout:"}
-{% extends 'blades/__html.njk' %}
-
-{% block body %}
-  <!-- YOUR page content -->
-{% endblock %}
+```jinja2
+{% extends 'blades/html.njk' %}
+{% include 'blades/gtm.njk' %}
 ```
 
-Example: https://github.com/anydigital/sveleven/blob/main/src/_theme/__layout.njk
-
-```liquid {data-caption="in .liquid layout:"}
-{% capture body %}
-  <!-- YOUR page content -->
-{% endcapture %}
+or:
 
-{% include 'blades/__html' %}
+```liquid
+{% include blades/html.liquid %}
+{% include blades/gtm.liquid for_body=true %}
+{% render blades/links, links: site.links, current_url: page.url %}
 ```
 
-Example: https://github.com/anydigital/sveleven/blob/main/src/_theme/__layout.liquid
-
-**Features:**
-
-- HTML5 DOCTYPE with language attribute (defaults to `en`, configurable via `site.lang`)
-- UTF-8 charset and comprehensive viewport meta tag with `viewport-fit=cover` for notched devices
-- Dynamic title generation with site title suffix (title is stripped of HTML tags and separated with `|`)
-- Favicon link (to `/favicon.ico`)
-- Automatic stylesheet linking from `site.styles` array
-- Inline styles from `site.inline_styles` array (joined with newlines in a `<style>` tag)
-- Automatic script loading from `site.scripts` array (with `defer` attribute)
-- Inline module scripts from `site.inline_scripts` array (joined with newlines in a `<script type="module">` tag)
-- Custom header content via `content_for_header`
-- Google Tag Manager integration (automatically rendered via `_gtm.{njk|liquid}` template for both `<head>` and `<body>` when `site.prod` and `site.gtm_id` are set)
+</details>
 
-**Variables:**
+<!--section:gh-only-->
 
-- `body` - The page content to be rendered inside the `<body>` tag (required)
-- `title` - Page title (optional, will be stripped of HTML tags)
-- `site.title` - Site title for the title suffix
-- `site.lang` - Language code (optional, defaults to `'en'`)
-- `site.styles` - Array of stylesheet URLs (optional)
-- `site.inline_styles` - Array of inline CSS strings (optional)
-- `site.scripts` - Array of script URLs (optional)
-- `site.inline_scripts` - Array of inline JavaScript strings (optional)
-- `content_for_header` - Custom HTML for the head section (optional)
-- `site.gtm_id` - Google Tag Manager ID (optional)
-- `site.prod` - Boolean flag for production environment (optional)
+---
 
-### Navigation <small>(`_nav.*`)</small>
+<!--section:appendix-->
 
-A navigation template `blades/_nav.{njk|liquid}` that renders a list of navigation links with proper accessibility attributes.
+<hgroup><small>Old-school</small><h2>Jekyll blades</h2><p></p></hgroup>
 
-**Parameters:**
+All CSS and HTML blades above are available as a Jekyll theme:
 
-- `nav_pages` - Array of navigation page objects with `url` and `title` properties
-- `current_url` - The URL of the current page (used to set `aria-current="page"`)
+<details><summary role="button" class="outline"><b>Install as Jekyll theme</b></summary>
 
-**Usage example with [Eleventy Navigation plugin](https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually):**
+In you `_config.yml`:
 
-```liquid {data-caption="in .liquid:"}
-{% assign nav_pages = collections.all | eleventyNavigation %}
-{% render 'blades/_nav', nav_pages: nav_pages, current_url: page.url %}
+```yaml
+remote_theme: anydigital/blades@v0.27.0-beta # or latest
+plugins:
+  - jekyll-remote-theme
 ```
 
-**Output:**
+Living example: https://github.com/anydigital/bladeswitch/blob/main/_config.yml
 
-```html
-<nav>
-  <a href="/">Home</a>
-  <a href="/about" aria-current="page">About</a>
-  <a href="/contact">Contact</a>
-</nav>
-```
+</details>
 
-<details><summary>
+Or use a preconfigured template:
 
-### Google Tag Manager <small>(`_gtm.*`)</small>
+[🥷 Bladeswitch Starter ↗ &nbsp;<small style="white-space: nowrap">Jekyll ⁺ Pico ⁺ Blades</small>](https://github.com/anydigital/bladeswitch){role=button .outline}
 
-</summary>
+---
 
-A template `blades/_gtm.{njk|liquid}` for embedding Google Tag Manager scripts in your pages.
+<div class="grid"><div>
 
-**Parameters:**
+Featured by:
 
-- `site.gtm_id` - Your Google Tag Manager container ID (e.g., `GTM-XXXXXXX`)
-- `site.prod` - Boolean flag to enable GTM only in production
-- `for_body` - Boolean flag (default: `false`). When `false`, renders the script tag for the `<head>`. When `true`, renders the noscript fallback for the `<body>`.
+- https://github.com/uhub/awesome-css
+- [awesome-eleventy](https://github.com/anydigital/awesome-11ty-build-awesome) list
 
-**Note:** This template is automatically included when using `__html.liquid`. You only need to manually render it if you're not using that base template, see examples:
+</div><div>
 
-- https://github.com/anydigital/blades/blob/main/blades/__html.njk
-- https://github.com/anydigital/blades/blob/main/blades/__html.liquid
+Credits:
 
-</details>
+- https://picocss.com/ for inspiration
+- https://11ty.dev/ for build power
+
+</div></div>

package/_includes/blades/gtm.liquid

@@ -1,3 +1,4 @@
+{% comment %}<!--section:code-->```liquid{% endcomment %}
 {% if site.prod and site.gtm_id %}
   {% capture _ %}
     {% unless for_body %}
@@ -21,3 +22,18 @@ height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
   {% endcapture %}
   {{ _ | strip }}
 {% endif %}
+{% # prettier-ignore %}
+{% comment %}```
+<!--section:docs-->
+Usage in Liquid:
+```liquid
+    ...
+    {% include blades/gtm.liquid %}
+  </head>
+  <body>
+    {% include blades/gtm.liquid for_body=true %}
+    ...
+```
+
+Living example: https://github.com/anydigital/blades/blob/main/_includes/blades/html.liquid
+<!--section-->{% endcomment %}

package/_includes/blades/gtm.njk

@@ -1,3 +1,4 @@
+{# <!--section:code-->```jinja2 #}
 {% if site.prod and site.gtm_id %}
   {# prettier-ignore-start #}
     {% if not for_body %}
@@ -20,3 +21,22 @@ height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
     {% endif %}
   {# prettier-ignore-end #}
 {% endif %}
+{#```
+<!--section:docs-->
+Usage in Nunjucks:
+```jinja2
+    ...
+    {% include 'blades/gtm.njk' %}
+  </head>
+  <body>
+    {% set for_body = true %}{% include 'blades/gtm.njk' %}
+    ...
+```
+
+Living example: https://github.com/anydigital/blades/blob/main/_includes/blades/html.njk
+
+Parameters:
+- `site.gtm_id` - Your Google Tag Manager container ID (e.g., `GTM-XXXXXXX`)
+- `site.prod` - Boolean flag to enable GTM only in production
+- `for_body` - Boolean flag (default: `false`). When `false`, renders the script tag for the `<head>`. When `true`, renders the noscript fallback for the `<body>`.
+<!--section--> #}

package/_includes/blades/html.liquid

@@ -1,4 +1,4 @@
-{% comment %} <!--section:code-->```liquid {% endcomment %}
+{% comment %}<!--section:code-->```liquid{% endcomment %}
 <!doctype html>
 <html lang="{{ site.lang | default: 'en' }}">
   <head>
@@ -36,17 +36,14 @@
   </body>
 </html>
 {% comment %}```
-
 <!--section:docs-->
+Usage in Liquid layout:
 
-To use in your layout:
-
-```liquid {data-caption=default.liquid}
+```liquid
 {% capture body %}...{% endcapture %}
 
 {% include blades/html.liquid %}
 ```
 
 Living example: https://github.com/anydigital/bladeswitch/blob/main/_includes/default.liquid
-
-<!--section--> {% endcomment %}
+<!--section-->{% endcomment %}

package/_includes/blades/html.njk

@@ -36,19 +36,16 @@
   </body>
 </html>
 {#```
-
 - `title | string` avoids error with `| striptags` when you pass a pure number.
 
 <!--section:docs-->
+Usage in Nunjucks layout:
 
-To use in your layout:
-
-```jinja2 {data-caption=default.njk}
+```jinja2
 {% extends 'blades/html.njk' %}
 
 {% block body %}...{% endblock %}
 ```
 
 Living example: https://github.com/anydigital/build-awesome-starter/blob/main/_includes/default.njk
-
 <!--section--> #}

package/_includes/blades/links.liquid

@@ -1,3 +1,4 @@
+{% comment %}<!--section:code-->```liquid{% endcomment %}
 <ul>
   {%- for link in links %}
     <li>
@@ -8,9 +9,19 @@
     </li>
   {%- endfor %}
 </ul>
+{% # prettier-ignore %}
+{% comment %}```
+<!--section:docs-->
+Usage with [Eleventy Navigation plugin](https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually):
 
-{%- comment %}
-  Compatible with:
-  - https://picocss.com/docs/nav
-  - https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually
-{%- endcomment %}
+```liquid
+{% assign links = collections.all | eleventyNavigation %}
+{% render blades/links, links: links, current_url: page.url %}
+```
+
+Usage inside Pico's Navar:
+
+```jinja2
+TBD
+```
+<!--section-->{% endcomment %}