wolfram-guide-page

name

wolfram-guide-page

description

Author a Wolfram Language guide page (a paclet's documentation home page that lists its functions, like the built-in guide/ pages) as a literate-markdown document and build it with MarkdownToNotebook. Use this whenever the user wants to write or generate a guide page, a paclet landing/overview page, or a curated function index for a Wolfram paclet - rather than hand-editing the DocumentationTools guide authoring notebook.

Authoring a guide page in markdown

MarkdownToNotebook fills the DocumentationTools guide authoring notebook (which DocumentationBuild turns into a guide/ page) from a literate-markdown document with the Guide template. A guide page is a paclet's documentation home: an abstract plus a curated, annotated list of the paclet's functions.

Before authoring, read https://github.com/WolframInstitute/MarkdownToNotebook/blob/main/docs/doc-pages.md - the Conventions across all doc pages section there covers the rules shared by Symbol, Guide, and TechNote pages (the [Symbol]() / backticks split, italics for argument names, EvaluateSeparator for state-threading, the <!-- => ... --> hints are author-only, the build-and-inspect loop, the no-Needs[…] rule, headless rasterization, ...). The worked example is the AccessibleColors guide at https://github.com/sw1sh/AccessibleColors/blob/main/docs/Guides/AccessibleColors.md ; model new guides on it.

Read first - the canonical guidelines (a guide page lives inside a paclet, so the Paclet Repository rules apply to it):

• Paclet Repository, creating paclets: https://resources.wolframcloud.com/PacletRepository/creating-paclets
• Paclet Repository, submission guidelines: https://resources.wolframcloud.com/PacletRepository/guidelines
• Wolfram Language code style: https://github.com/WolframInstitute/MarkdownToNotebook/blob/main/GUIDE.md

Frontmatter

---
Template: Guide
Name: GuideName
Title: Guide Title
Context: Publisher`PacletName`
Paclet: Publisher/PacletName
URI: Publisher/PacletName/guide/GuideName
Description: One-line summary of the paclet
Keywords: [keyword one, keyword two]
RelatedGuides: [OtherGuide, Accessibility]
Links: ["[label](https://example.com)"]
---

RelatedGuides are context-aware: a guide that is not the paclet's own (e.g. a System overview guide like Colors) links to paclet:guide/Name.

Sections

• ## Abstract - several sentences of context under the title. (If omitted, the Description frontmatter is used.)
• ## Functions - a markdown list, one item per function, each `Symbol` description. Each item becomes a docked "1-Line Function" entry: a chip linking to the symbol's ref/ page, an em-dash, and the inline-formatted description. The backticked symbol at the start is required for the link.

Group functions under ### Subheadings if the guide has sections of related functions. Keep the page a concise overview, not full documentation - the symbol reference pages (the wolfram-symbol-page skill) carry the detail.

Hierarchy (the sidebar tree)

Guides form a hierarchy through guide-to-guide links, not through folders. Every guide lives flat in Documentation/English/Guides/ and is addressed by the flat URI paclet:Publisher/PacletName/guide/Name - there is no nested guide/Topic/Name URI, and no shipped paclet puts guides in subdirectories. DocumentationBuild builds the collapsible navigation tree by scanning each guide for links down to its sub-guides, so a hub guide becomes a parent simply by pointing at them. (Verified against DocumentationBuildNavigation: ComputeLinkTrails` reads the parent→child graph from the source guides.)

Only one link form registers in the tree: a guide link that becomes a ButtonBox with ButtonData -> "paclet:.../guide/Name" inside a GuideFunctionsSubsection or GuideTOCLink cell. A plain inline [Name](paclet:.../guide/Name) reference in body prose, and the RelatedGuides: / Related-Guides section, do not count. MarkdownToNotebook emits the registering form for these two authoring patterns - use either or both:

1. Linked subsection heading - make a ## Functions subsection point at a fuller sub-guide by writing the ### heading itself as a guide link:

   ## Functions
   
   ### [NumberTheory](paclet:Wolfram/MyPaclet/guide/NumberTheory)
   - `Congruence` modular arithmetic
   - `QuadraticResidues` reciprocity and residues
   

   The whole heading must be the link (no trailing prose), or it stays plain text.

2. Dedicated ## Guides index - a curated list of sub-guides, separate from the function listing; each item becomes a GuideTOCLink:

   ## Guides
   
   - [NumberTheory](paclet:Wolfram/MyPaclet/guide/NumberTheory) primes, congruences, Diophantine equations
   - [GeometryTopology](paclet:Wolfram/MyPaclet/guide/GeometryTopology) curvature, manifolds, knots
   

Nest deeper by giving each sub-guide its own down-links (NumberTheory's guide links to ElementaryNumberTheory / AnalyticNumberTheory, and so on). The paclet's MainGuide is the root of the tree. Keep every guide .nb flat in Documentation/English/Guides/; the tree is the link graph, not the folder layout.

Build

(* MarkdownToNotebook is not on the public Function Repository yet, so use
   its public cloud deployment *)
mtn = ResourceFunction[ResourceObject["https://www.wolframcloud.com/obj/nikm/DeployedResources/Function/MarkdownToNotebook"]];
mtn["GuideName.md", "Documentation/English/Guides/GuideName.nb"]

Then build the paclet docs with DocumentationBuild. The guide is usually the paclet's MainGuide (set that relative path in the paclet's frontmatter; author the paclet with the wolfram-paclet skill).

Check

Before submission, run the docked Check button (top of every resource definition notebook) - it lints the document against the submission guidelines and reports hints by level. Headless, the same lint runs through DefinitionNotebookClientCheckDefinitionNotebook[nbo]` after stamping CellIDs and saving (the headless build does not assign CellIDs, and the scraper needs them to locate cells):

Needs["DefinitionNotebookClient`"]
UsingFrontEnd @ Block[{nbo = NotebookOpen[File["MyResource.nb"]]},
    CurrentValue[nbo, CreateCellID] = True;
    SelectionMove[nbo, All, Notebook];
    FrontEndTokenExecute[nbo, "Save"];
    Normal @ DefinitionNotebookClient`CheckDefinitionNotebook[nbo]
]

Each row is <|"Level" -> ..., "Tag" -> ..., "Parameters" -> ...|> with Level one of Suggestion / Warning / Error. Common tags to address before submission: DescriptionTooLong (shorten to under 128 chars), ExampleTextLastCharacter (end an example caption with :), FoundUnformattedCode (wrap a stray WL symbol in `backticks` or in an inferred link with empty parens like [Range]() (substitute the actual symbol name for Range), ThreeDotEllipsis (use … not ...), NotASystemSymbol (link foreign function-repo names instead of formatting them as system symbols), LargeCellBounds/CellHeight (rasterized output too big - crop it with #| tear: h or shrink the source). The repo's check.wls runs the same lint on every built .nb and prints a per-file summary.