@hutusi/amytis 1.14.0 → 1.16.0

package/content/books/sample-book/index.mdx

@@ -6,6 +6,9 @@ coverImage: "/images/flowers.jpg"
 featured: true
 draft: false
 authors: ["Amytis"]
+# Render each chapter's excerpt as a subtitle under its title.
+# Default is false; enabled here so the template demonstrates the feature.
+showChapterExcerpt: true
 chapters:
   - part: "Part I: Getting Started"
     chapters:

package/content/posts/code-block-features-showcase.mdx

@@ -0,0 +1,223 @@
+---
+title: "Code Block Features Showcase"
+date: "2026-05-25"
+excerpt: "Walk through the advanced code-block features: line numbers, line highlighting, title bars, diff colors, word-wrap toggle, and plaintext fallback."
+category: "Showcase"
+tags: ["test", "code", "shiki"]
+authors: ["Amytis Team"]
+toc: true
+---
+
+The default Shiki pipeline applies build-time syntax highlighting with a
+dual `github-light` / `github-dark` theme. The features below are opt-in
+via fence metadata.
+
+## Title bar
+
+```ts title="src/app.ts"
+export const greet = (name: string) => `Hello, ${name}!`;
+```
+
+## Line numbers
+
+```python linenos
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+```
+
+## Highlighted lines
+
+```rust {2,4-6}
+fn main() {
+    let x = compute();
+    println!("{x}");
+    if x > 10 {
+        warn();
+        recover();
+    }
+}
+```
+
+## Title + line numbers + highlights combined
+
+```tsx title="components/CodeBlock.tsx" linenos {3,7-9}
+import { highlightToHast } from '@/lib/shiki';
+import { toHtml } from 'hast-util-to-html';
+import CodeBlockToolbar from './CodeBlockToolbar';
+
+export default async function CodeBlock({ language, children, title }) {
+  const hast = await highlightToHast(children, language, { title });
+  const html = toHtml(hast);
+  return (
+    <div className="cb-root">
+      {title && <span className="cb-title">{title}</span>}
+      <CodeBlockToolbar code={children} />
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+```
+
+## Diff with red/green backgrounds
+
+```diff
+-export const VERSION = "1.0";
++export const VERSION = "2.0";
+ export const NAME = "amytis";
+-export const STAGE = "alpha";
++export const STAGE = "beta";
+```
+
+## Word-wrap toggle
+
+Long lines in code blocks overflow horizontally by default — the block grows
+a scrollbar at the bottom. Click the **Wrap** button in any block's header
+to soft-wrap long lines onto multiple visual lines instead; click again to
+restore horizontal scrolling.
+
+```bash
+curl -X POST "https://api.example.com/v1/items?fields=id,name,description,createdAt,updatedAt&sort=createdAt:desc&limit=100&offset=0&filter[status]=active&filter[category]=blog&include=author,tags" -H "Authorization: Bearer YOUR_API_TOKEN_HERE" -H "Content-Type: application/json" -d '{"name":"example","description":"a sufficiently long single line to demonstrate the wrap toggle"}'
+```
+
+Try the **Wrap** button in the header above ↑ to see the long line collapse
+into multiple soft-wrapped lines.
+
+## Mermaid still works (regression check)
+
+```mermaid
+graph LR
+  A[Markdown] --> B[remark]
+  B --> C[rehype + Shiki]
+  C --> D[Static HTML]
+```
+
+## Tabbed code groups
+
+Group adjacent fences into a single tabbed widget by wrapping them in a
+`:::code-group` container directive. Tab names come from the `[label]`
+token after the language. The mechanism is pure CSS (radio inputs + sibling
+selectors) — zero JavaScript, zero hydration cost.
+
+When a tab label matches a known package manager, language, or common
+config filename, an icon appears automatically before the label. Resolution
+is handled by `resolveCodeGroupIcon` in `src/lib/code-group-icons.ts`.
+
+:::code-group
+```bash [npm]
+npm install amytis
+```
+```bash [yarn]
+yarn add amytis
+```
+```bash [pnpm]
+pnpm add amytis
+```
+```bash [bun]
+bun add amytis
+```
+:::
+
+Filename labels also resolve — e.g. `tsconfig.json`, `vite.config.ts`, or
+`Dockerfile`:
+
+:::code-group
+```json [tsconfig.json]
+{ "compilerOptions": { "target": "es2022", "module": "esnext" } }
+```
+```ts [vite.config.ts]
+import { defineConfig } from 'vite';
+export default defineConfig({ server: { port: 5173 } });
+```
+```dockerfile [Dockerfile]
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN npm ci && npm run build
+```
+:::
+
+Tabs work across languages too — handy for showing the same algorithm in
+multiple implementations:
+
+:::code-group
+```ts [TypeScript]
+export function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+```
+```python [Python]
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+```rust [Rust]
+fn greet(name: &str) -> String {
+    format!("Hello, {name}!")
+}
+```
+:::
+
+## Notation comments
+
+Annotate individual lines with `// [!code …]` comments. Six markers are
+supported — focus, diff, highlight, error, warning — using the language's
+native comment style (`//` in C-family, `#` in Python, `--` in SQL, etc.):
+
+```ts
+function login(user: string) {            // [!code focus]
+  const token = oldApi.auth(user)         // [!code --]
+  const token = newApi.auth({ user })     // [!code ++]
+  validate(token)                         // [!code highlight]
+  throwIfExpired(token)                   // [!code error]
+  if (!token.refreshable) warn()          // [!code warning]
+  return token
+}
+```
+
+`// [!code focus]` dims the rest of the block so the focused subset stands
+out; hover the block to reveal the dimmed lines. `// [!code error]` /
+`[!code warning]` tint the line with a colored left-border (red / amber).
+`[!code ++]` / `[!code --]` color individual lines without needing a
+`diff`-language fence.
+
+Notation comments work in **any** language — Python:
+
+```python
+def fib(n):
+    if n < 2: return n          # [!code focus]
+    return fib(n-1) + fib(n-2)
+```
+
+## GitHub-flavored alerts
+
+Add a `[!TYPE]` marker on the first line of a blockquote to render it as a
+GitHub-style callout. Five types are supported, each with its own color,
+icon, and label:
+
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+
+rST equivalents (`.. note::` / `.. tip::` / `.. important::` / `.. warning::`
+/ `.. caution::`) render with matching colors via docutils' admonition
+directives — same visual treatment across both pipelines.
+
+## Explicit plaintext
+
+```plaintext
+This block opts out of syntax highlighting entirely. Use `plaintext` (or its
+aliases `text`, `txt`, `plain`) for prose-like blocks where token coloring
+would be noisy or misleading. Unknown language names will fail the build.
+```

package/content/series/rst-legacy/deeper-notes/images/test.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="160" height="80" viewBox="0 0 160 80">
+  <rect width="160" height="80" rx="10" fill="#d7efe3"/>
+  <text x="80" y="48" text-anchor="middle" font-family="sans-serif" font-size="18" fill="#21543d">rST</text>
+</svg>

package/content/series/rst-legacy/deeper-notes/index.rst

@@ -0,0 +1,15 @@
+Deeper Notes
+============
+
+:date: 2026-01-05
+:category: Legacy
+:tags: rst, notes
+:authors: John Hu
+
+This post uses a folder layout.
+
+Images
+------
+
+.. image:: ./images/test.svg
+   :alt: Test image

package/content/series/rst-legacy/getting-started.rst

@@ -0,0 +1,24 @@
+Getting Started With rST
+========================
+
+:date: 2026-01-03
+:excerpt: A simple rST-based post inside a legacy series.
+:category: Legacy
+:tags: rst, migration
+:authors: John Hu
+:redirectFrom: /posts/getting-started-rst
+
+Intro paragraph with an inline link to `Amytis <https://github.com/hutusi/amytis>`_.
+
+Overview
+--------
+
+- Keep the routing layer unchanged.
+- Parse the source format at the series boundary.
+
+Code Sample
+~~~~~~~~~~~
+
+.. code-block:: ts
+
+  export const feature = "rst";

package/content/series/rst-legacy/index.rst

@@ -0,0 +1,9 @@
+Rst Legacy Series
+=================
+
+:excerpt: Legacy notes imported from reStructuredText.
+:authors: John Hu
+:sort: manual
+:posts: getting-started, deeper-notes
+
+This is a small legacy series used to validate series-scoped rST support.

package/content/series/rst-readme/README.rst

@@ -0,0 +1,9 @@
+Rst README Series
+=================
+
+:excerpt: Legacy series metadata loaded from README.rst.
+:authors: John Hu
+:sort: manual
+:posts: readme-index-post
+
+This series uses README.rst as its series index file.

package/content/series/rst-readme/readme-index-post.rst

@@ -0,0 +1,10 @@
+README Index Post
+=================
+
+:date: 2026-01-09
+:excerpt: Post inside a series whose metadata is loaded from README.rst.
+:category: Legacy
+:tags: rst, readme
+:authors: John Hu
+
+Content for the README-indexed series.

package/content/series/rst-toctree/first-post.rst

@@ -0,0 +1,6 @@
+First Post
+==========
+
+:date: 2024-01-01
+
+This post appears second in the toctree order.

package/content/series/rst-toctree/index.rst

@@ -0,0 +1,10 @@
+Rst Toctree Series
+==================
+
+:excerpt: Legacy series order derived from toctree.
+
+.. toctree::
+   :maxdepth: 1
+
+   second-post
+   first-post

package/content/series/rst-toctree/second-post.rst

@@ -0,0 +1,6 @@
+Second Post
+===========
+
+:date: 2024-01-02
+
+This post appears first in the toctree order.

package/content/series/rst-toctree-precedence/first-post.rst

@@ -0,0 +1,6 @@
+First Post
+==========
+
+:date: 2024-01-01
+
+This post should remain first because explicit posts metadata wins.

package/content/series/rst-toctree-precedence/index.rst

@@ -0,0 +1,12 @@
+Rst Toctree Precedence Series
+=============================
+
+:excerpt: Explicit posts metadata should override toctree order.
+:sort: manual
+:posts: first-post, second-post
+
+.. toctree::
+   :maxdepth: 1
+
+   second-post
+   first-post

package/content/series/rst-toctree-precedence/second-post.rst

@@ -0,0 +1,6 @@
+Second Post
+===========
+
+:date: 2024-01-02
+
+This post should remain second because explicit posts metadata wins.

package/docs/ALERTS.md

@@ -0,0 +1,112 @@
+# Alerts (GitHub-flavored callouts)
+
+Amytis renders the five GitHub-flavored alert types as styled callouts.
+Both Markdown / MDX (`> [!TYPE]` blockquote markers) and rST (the built-in
+`.. note::` / `.. tip::` etc. directives) produce visually consistent
+output — same border color, same icon-less title bar for rST (docutils
+supplies the title), same per-type accent palette.
+
+## Markdown / MDX
+
+Start a blockquote with `[!TYPE]` on its own first line:
+
+```markdown
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+```
+
+The marker is **case-insensitive** (`[!note]` works too). Body content
+keeps full Markdown — paragraphs, lists, links, inline code, even other
+code blocks.
+
+A blockquote without a recognized marker stays as a plain blockquote.
+An unknown type like `[!UNKNOWN]` also passes through unchanged.
+
+## reStructuredText
+
+rST uses docutils' built-in admonition directives. All five GitHub types
+have a docutils equivalent, plus a few aliases:
+
+```rst
+.. note::
+
+   Highlights information that users should take into account.
+
+.. tip::
+
+   Optional information to help a user be more successful.
+
+.. hint::
+
+   Also styled as a tip.
+
+.. important::
+
+   Crucial information necessary for users to succeed.
+
+.. warning::
+
+   Critical content demanding immediate user attention.
+
+.. attention::
+
+   Also styled as a warning.
+
+.. caution::
+
+   Negative potential consequences of an action.
+
+.. danger::
+
+   Also styled as a caution.
+```
+
+The CSS rules in `src/app/globals.css` apply the same `--alert-accent`
+color variable to docutils' `.admonition-note` / `.admonition-tip` /
+`.admonition-hint` / `.admonition-important` / `.admonition-warning` /
+`.admonition-attention` / `.admonition-caution` / `.admonition-danger`
+classes, so `> [!NOTE]` in MDX and `.. note::` in rST land at the same
+visual output.
+
+## Visual style
+
+- Per-type accent color drives the left border, the title bar text, and
+  a tinted background (8% accent over the page background).
+- Dark mode uses brighter accent variants matching GitHub Primer's
+  dark-tier alert colors.
+- MDX alerts use an inline SVG icon; rST admonitions skip the icon (docutils
+  doesn't emit one) but keep the colored title.
+
+## How it works
+
+- **MDX**: a small remark plugin at `src/lib/remark-github-alerts.ts`
+  detects the `[!TYPE]` marker, strips it from the blockquote, and routes
+  the node through a `<GithubAlert>` React server component
+  (`src/components/GithubAlert.tsx`). `remark-gfm` v4 does NOT include
+  the alert transform — it passes blockquotes through with the marker
+  intact — so the plugin is what makes this work.
+- **rST**: docutils' built-in admonition directives produce the
+  `<aside class="admonition admonition-<type>">` markup. The shared CSS
+  in `globals.css` matches both pipelines.
+
+## Gotchas
+
+- Don't rely on a blank line between the marker and body — `> [!NOTE]\n> body`
+  works; `> [!NOTE]\n>\n> body` also works.
+- The marker must be `[!TYPE]` *exactly* (square brackets, exclamation,
+  type). VitePress-style colon variants like `:::tip` aren't recognized.
+- Custom alert types beyond the five GitHub ones aren't supported. If you
+  need one, extend the regex in `remark-github-alerts.ts` and add a CSS
+  rule.