Reuse content¶
The pymdownx.snippets Markdown extension can be used to include Markdown and
other content in a page. For example, common admonitions may be included from a
central location. Another common use is to centralize link definitions and
abbreviations. When a change is needed, definitions can be updated in one place
instead of requiring changes in many pages.
While this is a clear benefit, it is important that you should be able to inspect included content and its uses without trawling through the entire project. At the same time, you may want to see the assembled page in your editing environment without having to start a build. Zensical Studio supports both.
Example project
This workflow uses the project in acme-example-project.zip; the same reuse features work in any project.
Navigate to included content¶
Cmd/Ctrl-click the path after a snippet include (--8<--), or use
Go to DefinitionF12. Zensical Studio opens up
the snippet file and, if there is a fragment identifier, places the cursor
on the corresponding fragment.
Note how the annotation above the fragment says that it is referenced three times in the project. Clicking on this annotation opens an overlay that allows you to preview the locations where the snippet is used. You can double-click on one of them to open the location.
Preview pages with snippets¶
Zensical Studio's Markdown preview resolves snippet includes, even nested ones. Instead of seeing your page with the snippet syntax and having to switch to a different editor, you can see what the end result of the snippet resolution is: a complete rendered page.
Take workspace-settings.md, for example. It includes both an admonition
about admin rights and a "Need help" section at the end. If you open the
Markdown preview and navigate to the locations of the snippet includes,
you will see that the included content is rendered in the page.
