MarkdownPanel

Embed a full-fledged markdown documentation system.

ID	Default Value	Description
Font	Oxygen Bold	the font being used for the paragraph text
FontSize	14.0	the font size (will also scale everything else).
ShowToc	true	shows the TOC
ShowSearch	true	display the search box
ShowBack	true	display the navigation buttons
BoldFontName	""	the font being used for bold / headlines
FixTocWidth	-1	a fixed width for the TOC (might be helpful to align the doc layout to your interface).
StartURL	/	no description
ServerUpdateURL	""	no description
CustomContent	""	no description

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.

Topbar

Icon	Description
	Toggles the table of contents on the left edge
	Show the documentation update window.
	Navigate back (just like with any browser)
	Navigate forward.
	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 keyword 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.

Search box

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.

Display

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.

Item	Description
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

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

Cache-based means that the content (text and images) are retrieved from two files:

1. a file for all "text" called content.dat
2. a file containing all images called images.dat .
   

There's also a third file called hash.json 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 CachedDocumentation (for HISE) and Documentation (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