Documentation guide

The online documentation to GridLAB-D is delivered using the SLAC Gismo Document Browser hosted at http://docs.gridlabd.us/. Documents are displayed by retrieving the content directly from GitHub in the project docs folder. The docs folder contains the documentation hierarchy for users, with all developer documentation in the Developer folder.

General Documentation Template

Documents are generally formatted using Markdown syntax using the following template:

[[/Folder/Name]] -- Document topic

# Synopsis

Context:
~~~
template or example
~~~

# Description

Provide an overview of the topic and an outline of subtopics.

## Details

Provide sections with details on each subtopic.

# Example

Describe the example.

~~~
provide the example
~~~

# Caveat

Describe caveats related to the topic, if any.

# See also

* [[/Folder/See]]
* [[/Folder/Also]]

Special Markdowns

The following special Markdown features are supported by the document browser.

Document References

References to other documents in the project docs folder may either written as a reference to [[Local]] document or a reference to a file [[/In/Another/Folder/My_File]]. When referencing a file in another folder, the link is formatted at My File (In Another Folder).

Math

Math equations using the MathJax system may be embedded using either $inline$ or

$$
block
$$

formatting.

Images and Videos

Images may be embedded by using a document reference with the tag image: prefix. The following example embeds my_image.png from the same folder as the current document.

[[image:my_image.png]]

If you specify an absolute path, the image will be obtained from the docs folder.

Similarly, a video from YouTube may be embedded using the video: prefix. The reference will use the https://www.youtube.com/embed/ prefix applied to the video name given to embed the video in the document.

Transcluded Code

Code from the current GitHub repository may be embedded using the code: prefix. The same project, owner, and branch will be used as the documentation. The source will be referenced from the GitHub project's root folder. For example, the following code will embed the file my-folder/my-file.txt:

[[code:my-folder/my-file.txt]]

Buttons

The document may include a clickable button using the following syntax:

((url))