Lildocs

Technical Documentation

Help readers make correct decisions quickly: organize around tasks and concepts, state boundaries plainly, and prove claims with concrete examples.

Read the Project

Base documentation on the current project's facts, vocabulary, and support boundaries:

• existing docs and README
• docs root, folder layout, and generated navigation
• package scripts and CI workflows
• guides and fixtures used by the project
• configuration, theme, font, and asset files

When publishing behavior matters, verify it from the installed package docs or source before writing about it:

node_modules/lildocs/docs/
node_modules/lildocs/

Use published docs only when local package docs are unavailable:

https://aleclarson.github.io/lildocs/

Treat generated-site constraints as content constraints: folder-based navigation, static links, headings and anchors, local search, diagrams, and assets all affect how readers find and trust the docs.

Page Purpose

Give each page one durable job. Before drafting, decide what the reader is trying to do, what they already know, what decision the page must support, and where they should go next.

General Technical Documentation Guidelines

Apply these guidelines to explanatory content throughout the docs. The home page's established slogan remains the intentional branding exception described below.

1. Start with the reader's problem, decision, or task.
2. Explain when the tool is useful and how it differs from common alternatives.
3. Use plain, direct language; avoid slogans, marketing, and unnecessary jargon.
4. State limits, costs, prerequisites, and failure cases beside the benefits they qualify.
5. Support important claims with runnable examples, output, or observable results.
6. Make examples complete, internally consistent, and safe to copy.
7. Explain placeholders clearly and never present incomplete commands as pasteable.
8. Show how readers can verify both successful and failed operations.
9. Organize content as a funnel: quick orientation, working example, mental model, then reference.
10. Give each page one clear purpose and direct readers to the page that owns deeper concepts.
11. Keep advanced internals and optional workflows out of the required beginner path.
12. Use consistent terminology across pages.
13. Add diagrams only when relationships, ownership, flow, or branching are easier to understand visually.
14. Validate commands, links, examples, formatting, and the generated documentation site before publishing.

Home Page

Treat the home page as the project's introduction, not as a map of the docs. Use the project's canonical display name as the H1 and its established slogan/tagline as the plain blockquote immediately below it. Prefer wording from the project's README or package metadata, and do not replace it with a generic title such as Introducing <name> or <name> Documentation.

# lildocs

> A lightweight CLI that turns Markdown docs into a static searchable
> documentation site.

This branding blockquote takes precedence over the general purpose-blockquote rule below; the rest of the home page can orient readers and link to the next steps.

For new pages in this project, follow the H1 with a purpose blockquote unless nearby docs use a different contract. The blockquote should clarify the page's real job: the decision it supports, the task it helps complete, or the boundary it draws.

# Command Line

> Build, preview, and publish flows start from different commands; this page
> keeps their flags and defaults separate so scripts stay small.

Weak purpose blocks restate the title or promise generic learning.

# Configuration

> Learn about configuration.

Prefer direct clarity over page-navigation language.

# Configuration

> Persistent site defaults belong in `config.json`; one-off choices belong in
> CLI flags for the current build or preview command.

Information Architecture

Organize docs by reader movement, not by source-code ownership. A useful docs set has a few clear shapes:

• Overview: names the system, its moving parts, and the first meaningful decisions.
• Task guides: complete a workflow from prerequisite to successful result.
• Concept guides: explain boundaries, tradeoffs, and mental models.
• Reference: supports lookup with complete, scannable facts.
• Troubleshooting: starts from symptoms and leads to verification.

Put concepts at the point where readers need them. If a concept is needed by many pages, give it a canonical home and link to it instead of redefining it in each workflow.

Use file and folder names as navigation labels. Prefer short, stable nouns for concept areas and action-oriented names for workflows:

docs/
  index.md
  getting-started.md
  guides/
    publish.md
    customize-theme.md
  concepts/
    navigation.md
  troubleshooting.md

Keep prerequisite information before the steps that depend on it. Keep conceptual tradeoffs before the choice they influence. Put warnings immediately before the action they can change.

Mermaid Diagrams

Use a Mermaid diagram when visual structure helps the reader understand a relationship they would otherwise need to reconstruct from prose. Diagrams are especially desirable for:

• workflows with meaningful branches, parallel steps, or feedback loops
• lifecycle states and the transitions allowed between them
• dependencies, ownership boundaries, or handoffs among several components
• request or message sequences involving multiple actors
• architecture overviews where grouping and connection are the point

Prefer flowchart for workflows, dependencies, and architecture; sequenceDiagram for interactions over time; and stateDiagram-v2 for lifecycle transitions. Keep each diagram focused on one idea, use short labels, and introduce it with prose that tells the reader what relationship to notice.

Do not add a diagram merely to decorate a page or restate a short linear list, definitions, headings, or a comparison that a table communicates more clearly. If layout, direction, grouping, or connection carries no additional meaning, use prose, a list, or a table instead.

Callouts

lildocs supports GitHub-style Markdown callouts. Use them when a detail changes how the reader should interpret or perform the surrounding task:

• NOTE: useful context that prevents confusion but does not change the task
• TIP: optional advice that improves the result or saves time
• IMPORTANT: required information that readers must know before continuing
• WARNING: risk, data loss, compatibility, or irreversible action to check
• CAUTION: hazardous or easy-to-misuse behavior that needs extra restraint

Keep callouts close to the step, option, or concept they affect. Do not use a callout for ordinary prose, page summaries, or content that belongs in the main flow.

> [!NOTE]
> Search indexes are generated at build time, so changed pages require a new
> build before local search reflects them.

> [!WARNING]
> Delete the output directory only when it contains generated site files.