Embed a full-fledged markdown documentation system.
||Oxygen Bold||the font being used for the paragraph text|
||14.0||the font size (will also scale everything else).|
||shows the TOC|
||display the search box|
||display the navigation buttons|
||the font being used for bold / headlines|
||-1||a fixed width for the TOC (might be helpful to align the doc layout to your interface).|
If you read the documentation inside HISE, you're most likely looking at this Floating Tile at the very moment. However you can also use this to display the documentation of your own project as embedded help system.
There are four components in the Markdown Panel: the topbar, the TOC, the search box and the display.
|Toggles the table of contents on the left edge|
|Show the documentation update window.|
|Navigate back (just like with any browser)|
|Toggles the colour scheme.|
|Toggles between scroll and select mode.|
|Use the search engine|
|Unlocks the editing mode|
If you're using the Markdown Panel in your project, you can hide certain elements of this topbar using the properties.
Table of Contents
The table of contents is the navigation map for the documentation and shows a tree of all pages including headlines up to level three (those prepended with
It does not show the file name but the first
property from the YAML header. This is because the filenames have to follow the URL specification (no uppercase and whitespace) and would make your TOC like a directory structure from MS-DOS 6.0...
For a complete explanation of the YAML header please take a look here ...
If you're in editing mode, it has a useful context menu that offers many tools to accelerate your documentation creation process.
The search box offers a quick way to find the information you're after and should be the very first thing you do if you get stuck somewhere. It has a fuzzy search matching algorithm and some manual sorting optimizations to give you the best matches first. As soon as you start typing, it will show a popup with the matches.
The search engine does not utilize a full text search, but rely on keywords and weight property in the YAML header of a file.
This is the only non-optional part of this UI component and shows the current page. Depending on the mouse mode you can drag-scroll or select text paragraphs.
There are also a few interactive elements like:
- interactive script editor. Run the script directly in place
- GIF frame. Click to play the GIF
- code editor with automatic copy to clipboard button
If you're in editing mode, there's some useful tools in the context menu which allow to edit the current page in the editor or create a properly formatted markdown link.
|Export||Shows the documentation update window.|
|Copy Link||Copies the current URL of this page into the clipboard. If you want to paste it in your docs, use Create Markdown formatted link instead.|
|Edit this page in new editor tab||Opens the markdown file that renders this page in a new tab next to the existing markdown editor. To make this function work, you need to have at least one Markdown Editor inside a Tab .|
|Create Markdown formatted link||This creates a link based on the last anchor from where you clicked which is properly formatted and ready to be pasted into the markdown doc.|
|Show File||Reveals the currently shown file in the OS specific file browser.|
|Debug current content||This is an advanced feature and shows the exact markdown code that is being rendered right now, which might be enhanced by autogenerated content for the internal HISE docs. You shouldn't bother about this if you're writing the docs for your project.|
This context menu is also available in the TOC, which might be an even better way to grab links to other pages.
Updating the documentation
In order to understand the purpose of this window, we need to know that the entire markdown system is based on two different "source modes":
File-based means that the content that is being shown, the items that are visible in the TOC and the images are all taken from actual files in the file system. This is the mode that you use when you are creating or editing the documentation.
Take a look here for a detailed explanation of the file-based system
Of course this might be very messy for the end user which is why there is another mode:
Cache-based means that the content (text and images) are retrieved from two files:
- a file for all "text" called
- a file containing all images called
There's also a third file called
which just contains the hash of these files to let the server know if the docs needs to be updated).
This mode is used by the compiled project. The idea behind this is that it heavily simplifies the distribution of the docs to the end user (also the look up will be a bit faster for the cached version).
The files are being stored in the app data directory's subfolder
(for HISE) and
(for compiled projects). Normally you shouldn't bother about this because it will automatically copy the files there when you update the docs from the server.
The same thing is true for the HISE documentation: as long as you don't fork the doc repository and tell HISE where to find it, you'll be using the cached files that HISE fetches from the server.
If you're editing the HISE documentation, you can simply switch between file-based mode and cached mode using the button at the right edge of the topbard (either the lock or the pen).
Now the window above can be used to compile all markdown files and images into these cache files or to just fetch the cached files from the server to update the documentation. There's also a third option which allows you to create a 1:1 HTML copy for showing a static website with the same content