Imported from WolframInstitute/MarkdownToNotebook (
skills/wolfram-symbol-page/SKILL.md). Install upstream withnpx skills add WolframInstitute/MarkdownToNotebook --skill wolfram-symbol-page. Copyright stays with the author.
Authoring a symbol reference page in markdown
MarkdownToNotebook fills the DocumentationTools symbol authoring notebook (which
DocumentationBuild turns into a ref/ reference page) from a literate-markdown
document with the Symbol template.
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 examples are
the symbol pages of the AccessibleColors paclet at
https://github.com/sw1sh/AccessibleColors/tree/main/docs/Symbols ; model new
pages on them.
A symbol page documents one symbol and belongs to a paclet (author the paclet with
the wolfram-paclet skill, the guide with wolfram-guide-page).
Read first - the canonical guidelines (a symbol ref 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: Symbol
Name: SymbolName
Context: Publisher`PacletName`
Paclet: Publisher/PacletName
URI: Publisher/PacletName/ref/SymbolName
Keywords: [keyword one, keyword two]
SeeAlso: [RelatedSymbol, AnotherSymbol]
RelatedGuides: [GuideName]
---
SeeAlso and RelatedGuides are context-aware links: a System symbol links to
its system ref page, a paclet symbol to the paclet's ref page (the converter
resolves this). URI is the page's ref/ path.
Hierarchy (where a symbol sits in the tree)
The documentation hierarchy is a tree of guides; symbol reference pages hang off it - a symbol's place is "which guide owns it." Two links establish that, in opposite directions:
- Up (symbol → guide): list the owning topic guide in
RelatedGuides:. It renders as the page's Related Guides section, andMarkdownToNotebookemits it as the plainButtonBox[…, BaseStyle -> "Link", ButtonData -> "paclet:…/guide/Name"]link thatDocumentationBuild's related-guides harvester reads - aTemplateBox"RefLinkPlain" (an inline guide mention) would not be harvested. Point it at the single most specific guide that owns the symbol (e.g. aCongruencepage usesRelatedGuides: [ElementaryNumberTheory], not the top-level paclet guide). - Down (guide → symbol): the owning guide must list the symbol in its
## Functionssection (a`SymbolName`chip). That is authored on the guide, not here - see thewolfram-guide-pageskill. A symbol no guide lists is an orphan in the tree.
SeeAlso: is lateral, not hierarchy - it links sibling symbols (rendered as typed
PackageLink chips) for peer "see also" cross-references.
The visible sidebar tree (main guide → topic guides → sub-topic guides) is built
entirely from guide-to-guide links, not from symbol pages - see the Hierarchy
section of the wolfram-guide-page skill. Symbol pages do not nest in
subdirectories: like guides they stay flat in
Documentation/English/ReferencePages/Symbols/, addressed by the flat URI
paclet:Publisher/PacletName/ref/Name.
Sections
-
## Usage- one statement per paragraph. Usage lists only input/construction signatures — theDownValuesformsSym[args]that call the symbol to build a result. Instance application (obj[input]), property/method access (obj["prop"]), and parameter substitution areSubValues(behavior of an already-constructed object) and belong in## Details/## Scope/## Properties and Relations— never Usage. For an object-head symbol, anobj[…]action line in Usage is a category error. The canonical signature form wraps the whole signature in an inline<code>tag so markdown viewers process the nested markdown inside it (links, italics, math) while rendering the whole span in code style. Substitute the actual symbol and argument names; the examples below use a hypotheticalMyFunc[x_1, x_2]:<code>[MyFunc]()[$x_1$, $x_2$]</code> gives the result, computed from $x_1$ and $x_2$.GitHub and Pandoc render this as a code-styled clickable link (the symbol's ref page - here, the
MyFuncref page), then literal brackets, then italic x₁, x₂. The converter strips the<code>wrapper, peels the[Name](…)link down to the name, drops*…*italics around args, and rewrites$x_i$to the template formx$ibefore handing the reconstructed signature to DocumentationTools' usage template-parser. Bare backtick / prose / hybrid forms still work as fallbacks. -
## Details & Options- bullets becomeNotescells; pipe tables become grids. Always document a symbol's options as a GitHub pipe table here, in## Details & Options- never as prose bullets, and never deferred to a separate## Optionsexample section. Use three columns - the option name, its default, and the effect - wrapping the name and default each in<code>…</code>:| option | default | effect | |---|---|---| | <code>"OptionName"</code> | <code>Default</code> | what the option does |MarkdownToNotebookturns this into the3ColumnTableModoptions grid (the same cell the palette's Options Table button inserts,Options[Symbol]-keyed). Put it after the notes bullets, optionally with a one-line lead-in; if the symbol takes no options, omit the table. A lower## Optionssection (among the example sections) is only for demonstrating options with example cells - never the reference table itself. Link another symbol inline by wrapping its actual name in the inferred-link form, e.g.<code>[Range]()</code>to linkRange,<code>[WCAGContrastRatio]()</code>to link a paclet symbol - the literal name goes between the brackets, never the word "Symbol". Two things matter here: the empty parens (without them markdown viewers do not render the[…]as a link element), and the<code>wrapper (markdown forbids nested formatting inside backticked code spans, but processes markdown inside an inline HTML element - so the[link]()inside<code>renders as a clickable link with code styling). The converter strips the wrapper, routes the empty-URL link to apaclet:ref in the notebook, and the twin rewrites it to the public web URL. -
## Basic Examplesthen the extended sections## Scope,## Options,## Applications,## Properties and Relations,## Possible Issues,## Neat Examples. The example-authoring rule (one demonstration per cell, one-sentence:-terminated caption,---between siblings,### Headingbecomes anExampleSubsection) is documented once in docs/examples.md - follow it everywhere example cells appear.
Examples and outputs
A fenced wl cell is evaluated; record the expected result in an
<!-- => ... --> HTML comment after the cell (it documents the output and is
stripped from the page). To load the paclet so examples run, give the Context
frontmatter; the converter inserts the Needs[...] initialization. #| cell
options (eval, screenshot, tear, flag) work as elsewhere; inline math is
$...$.
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["SymbolName.md", "Documentation/English/ReferencePages/Symbols/SymbolName.nb"]
Then build the paclet docs with DocumentationBuild. DocumentationBuild drops (with
a warning) a See Also link whose ref page is missing from the local index - new
System symbols may warn locally yet resolve in a published environment.
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.
