GoCalf Calf 的自留地 · 昙花一现
由 AI 生成

Write content

Use ordinary Markdown first: headings, lists, tables, links, quotes, fenced code and native Hugo footnotes. The safe renderer does not require raw HTML. Optional components, structured tables, code resources, diagrams/media, interactive charts and opt-in JSX tools solve specific tasks; see a small live example.

Story typography and AI disclosure

yaml
---
title: An unhurried walk
type: story
params:
  ai_label: polished
---

Native type: story selects larger prose, indented/justified paragraphs and decorated headings in shared article bodies. Other native types keep ordinary styling; it is not a preset or content organization model. cascade.type: story applies it to a branch; a local non-story type opts out. Lists/code/captions are not indented prose.

params.ai_label is an explicit editorial statement, independent of type, author identity and license. Supported strings are manual, reviewed, polished, generated; empty clears. Labels are localized as Written entirely by a human, AI-reviewed, AI-polished, AI-generated. Do not write ai-generated as the enum or apply a default unless it is true for that content. Icons-off retains disclosure text. Disclosure labels use adaptive palette text colors: blue for human-written, green for AI-reviewed/AI-polished, and orange for AI-generated. Their words carry the disclosure independently of color.

markdown
[Read a page](../other/index.md)
[Read its heading](../other/index.md#useful-heading)
[Return to a branch](../_index.md)

Links are relative to the actual source file directory, not its dated published URL. Include exact index.md, _index.md or plain filename; no basename search or invented aliases. Exact resources resolve within/cross bundles and global assets. Queries/fragments survive. Encode spaces or use angle destinations; explicit index.zh.md selects that actual language, not an automatic translation switch. Moving source may require link edits; changing only permalink rules does not.

Ordinary public/web paths remain authored URLs and are not crawled. [Home](/) means host root, not the current language/deployment path. Use source _index.md links, native pageRef, or the configured-Markdown native Home extension when you need those prefixes. Missing .md destinations warn; strict builds fail. Optional site link_heading_checks: true checks native heading fragments, not every shortcode or custom HTML ID. External HTTP(S) links open safely in new tabs.

Images, captions and attributes

markdown
![An observable pattern|320](pattern.svg "Caption from title")
{.invert-when-dark #pattern loading="eager"}

Import the parser defaults from Getting started. A direct standalone image gets a caption from nonempty title, then cleaned alt. Alt remains alternative text; terminal positive |width or |widthxheight supplies native dimensions. Backgrounds are transparent; artwork bytes are never recolored. Default thumbnails use lazy loading and async decoding; optional eager loading is useful for an opening image. No dimensions are invented when absent.

auto_caption: false disables automatic captions for a page/default; .no-caption suppresses one image. Prose-inline, linked, list and table images do not get automatic figures. Explicit shortcode/figure captions remain. Native next-line attributes work on standalone images; loose-list indentation matters and tight-list image attrs may not attach. This is Hugo syntax, not every inline-attribute dialect.

invert-when-dark / invert-when-light filter the marked element itself. Image classes do not invert captions; a marked container filters the whole group. Nested filters compound. Add invert-soft on the same element to use 93% inversion with a 180° hue rotation instead of the default 100%:

markdown
![Light-authored diagram](diagram.svg)
{.invert-when-dark .invert-soft}

invert-soft alone has no effect and does not change a descendant’s inversion strength. Paired with invert-when-light, it applies only in light mode. Both direction classes together always invert; adding invert-soft makes that always-on conversion 93%. Image and diagram viewers preserve the chosen effect when expanded and when the site mode changes. The effect is visual only; original downloads retain their source bytes.

Use the image shortcode for explicit background, reliable nested attributes, caption or original-image access. No automatic gallery/lightbox is added to ordinary Markdown images.

Alerts, code and math

Native blockquote alerts use > [!NOTE], TIP, IMPORTANT, WARNING or CAUTION, followed by quoted Markdown. Ordinary fences have native Chroma highlighting, copy UI and manual fallback. Ordinary code fences and snippets are data, never executed. The separate opt-in jsx-live fence is explicitly executable content.

With the passthrough import, $x^2$ is inline math and $$...$$ is display math. Escape literal currency as \$; code remains non-math. Native build-time KaTeX emits HTML+MathML with trust disabled and strict errors. Matching local CSS/fonts load conditionally, with no client math runtime or CDN. Wide display math scrolls locally. Malformed TeX fails; arbitrary commands, global macros and universal CSP/AT support are not promised. Describe formulas in prose for search: math subtrees are excluded.

Hugo’s Markdown guidance covers the underlying engine. Avoid useEmbedded='always' if you need theme render hooks.

子文档

  • Compose content

    Containers combine Markdown without turning raw HTML on. Use outer % notation for the outermost container and nested < notation for every inner component. Self-contained leaves always use <, even alone. Blank lines matter. text 复制 {{% …

  • Structured tables

    Use native Markdown tables for simple rows and columns. rich-table adds multiple header rows, merged header/body cells and Markdown-rich cell content. It emits a native table with explicit header associations, not an interactive …

  • Include code resources

    Put a text/code file beside your bundle’s index.md or _index.md and use: text 复制 {{< snippet src="example.py" from=2 to=5 options="linenos=table,hl_lines=2" >}} The rendered selection has native highlighting, copy controls and a full-source …

  • Diagrams, video and badges

    These are optional content interfaces with distinct loading and privacy behavior. Literal examples here do not activate a renderer/provider. The shortcode reference owns their arguments. #Mermaid text 复制 ```mermaid {caption="Read, then …

  • Interactive charts

    Use an echarts fence or shortcode for interactive line, bar, pie/donut and scatter charts. Both accept the same strict JSON configuration and share one renderer. No front-matter flag, npm installation or remote chart service is needed. The …

  • Interactive JSX

    Add small React tools to ordinary .md articles with a jsx-live fence or jsx shortcode. Hugo compiles JSX; the browser runs the component. No MDX conversion, Node compilation step, CDN, or npm installation is needed for the bundled React …

  • A small working example

    This page renders a local component, formula and code resource. It does not load a comment provider, badge, remote image, video or diagram library. Its adjacent source is a downloadable resource, never an executable build step. #A useful …