| name | wolfram-demonstration |
| description | Author a Wolfram Demonstration (a deployable interactive Manipulate-based visualization for the Wolfram Demonstrations Project) as a literate-markdown document and convert it to the official authoring notebook with MarkdownToNotebook. Use this whenever the user wants to create, write, draft, or publish a Wolfram Demonstration, an interactive Manipulate, an explorable visualization for demonstrations.wolfram.com - especially when they would rather write markdown than hand-edit notebook cells. Also use it when asked to add snapshots, caption, or metadata to such a Demonstration. |
Authoring a Demonstration in markdown
MarkdownToNotebook fills the official Wolfram Demonstrations authoring notebook
(the one File > New > Demonstration opens, with its docked HELP / EXAMPLE /
SAVE / UPDATE THUMBNAIL AND SNAPSHOTS / TEST IMAGE SIZE / UPLOAD toolbar) from a
literate-markdown document. A Demonstration is built around exactly one
Manipulate[...] expression that visualizes one concept; the deployable artifact
is a signed .nbp (a CDF the free Wolfram Player can run) plus its
auto-generated thumbnail and snapshots. The author writes YAML frontmatter and
## section headings; the converter chooses every cell style. Use the
Demonstration template.
Model new documents on the worked example -
https://github.com/WolframInstitute/MarkdownToNotebook/blob/main/examples/BlochSphereGates.md -
and read https://github.com/WolframInstitute/MarkdownToNotebook/blob/main/docs/resource-notebooks.md
(the "Demonstration" section) for the slot-by-slot mapping.
Read first - the canonical guidelines:
Frontmatter
Fence a key: value YAML header with --- at the very top:
---
Template: Demonstration
ResourceType: Demonstration
Name: My Title in Title Case
ContributedBy: Author Name
AuthorNames: Author Name # one entry, or a list for multi-author submissions
Keywords: [keyword one, keyword two]
Categories: [Mathematics, Geometry]
RelatedDemonstrations: ["[Other Title](http://demonstrations.wolfram.com/OtherTitle/)"]
Links: ["[External resource](https://example.com)"]
SubmissionNotes: One sentence for the reviewer
---
Name is the page title; use Title Case with all major words capitalized, be
specific ("Density Map for the 3n+1 Problem", not "3n+1 Problem"), and use
ASCII only - the URL slug is derived from it.
Categories should come from the official Topics taxonomy;
the top-level branches are Mathematics, Computation, Physical Sciences,
Life Sciences, Business & Social Systems, Engineering & Technology,
Systems / Models / Methods, Art & Design, Creative Arts, Everyday Life, and
Kids & Fun (each with its own subtree).
Sections (each ## Heading fills a slot)
Required:
## Caption - one short paragraph, three to five sentences, that explains what
the Demonstration shows. Text only - no code, no graphics. Do not copy text from
books or the web. This shows under the thumbnail on the published page.## Initialization - one wl cell with all helper definitions the Manipulate
needs. Everything that is not part of Manipulate[...] itself must live here -
the Manipulate cell should be the Manipulate and nothing else. Include
SaveDefinitions -> True on the Manipulate whenever this section is non-empty.## Manipulate - one wl cell whose expression is exactly one Manipulate[...].
No nested Manipulates, no function that returns a Manipulate. The submission
review rules forbid InputField and Appearance -> "Open". Set
Appearance -> "Labeled" on sliders that should show their numeric value, and
pick ImageSize -> {w, h} so the panel does not jiggle as controls move.## Snapshots - three or more wl cells, each producing one Manipulate panel
at a distinct parameter set (a static Show[...] / Plot[...] that reproduces
what the Manipulate would render at those parameters is fine). The site requires
at least three snapshots and they should illustrate the range of behavior.
Each snapshot is its own captioned demonstration with a --- separator
between siblings - the docs/examples.md rule, applied to the
snapshot strip.
Optional:
## Details - extended description, formulas (inline math as $...$),
variable definitions, snapshot captions. Text only - no code, no graphics.## References - one numbered reference per item. Book references go Author,
Title (italic), City: Publisher, year; article references Author, "Title",
Journal (italic), Volume(Issue), year, pp. X-Y.
Manipulate authoring rules
These come straight from the Demonstrations review checklist; cells that violate
them will be rejected:
- Exactly one
Manipulate, top level, not nested.
- No
InputField and no Appearance -> "Open" controls.
- Lower-case descriptive labels on every control (
"number of subdivisions",
not "n"). Only proper nouns and adjectives capitalized.
- Fixed image size - the Manipulate panel must not resize as controls move.
Use
ImageSize -> {w, h}, PlotRange -> All, ImagePadding, Pane, or
Spacers to keep it stable. For 3D, SphericalRegion -> True.
- Initialization stays in
## Initialization - never define a helper inside
the Manipulate cell. Pair non-empty Initialization with SaveDefinitions -> True.
- Localize every control variable and helper with
Module / DynamicModule -
unlocalized variables cause cross-talk between panels.
- For slow updates,
SynchronousUpdating -> False; for stuttering sliders,
ContinuousAction -> False.
Code-cell options
A fenced wl cell carries #| option lines at the top (the Quarto cell-option
convention), one key: value per line: eval: false (show code without running),
file: path (replace the body with a local file or URL), screenshot: true
(rasterize a produced Notebook), tear: h (torn-paper screenshot capped to h
points). The Manipulate cell is auto-evaluated and the rendered panel becomes the
Manipulate output below the Input cell, the way the front end shows it.
Build & deploy
wolframscript -f build.wls
The notebook the converter writes carries the same docked HELP / SAVE / UPDATE
THUMBNAIL AND SNAPSHOTS / TEST IMAGE SIZE / UPLOAD toolbar a hand-authored
Demonstration has. Click UPDATE THUMBNAIL AND SNAPSHOTS (it regenerates them
in place), then UPLOAD to send the .nb to the Demonstrations Project review
queue. Submissions are reviewed editorially - allow a few weeks. Successful
submissions are republished as a signed .nbp (CDF) at
demonstrations.wolfram.com/<TitleCamelCase>/ with a thumbnail, snapshots,
caption, and your name.
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.
