Contributing > Markdown Conventions




Infoboxes

We include four types of “infoboxes”. an action item, for items that really need attention; a todo, for suggesting future improvements; a more normal infobox for extra information on a topic; and a warning box to attract extra attention. Specifying these is as simple as using a liquid command to including a file while defining the body.

Note that because you will enclose content in HTML, you have to format the content in HTML rather than markdown. For example, HTML here is rendered by literally writing <code>HTML</code> instead of `HTML`.

Action Item

The action item looks like this

This is an action item.

and can be written up in markdown like this

{% include alerts/doctodo.html body="This is an action item." %}

Todo

The hopefully inviting todo looks like this

This is an inviting todo.

and can be written up in markdown like this

{% include alerts/todo.html body="This is an inviting todo." %}

Infobox

The infobox looks like this

This is an infobox for extra information.

and can be written up in markdown like this

{% include alerts/info.html body="This is an infobox for extra information." %}

Warning

A warning looks like

Danger, danger Will Robinson.

and can be written up in markdown like this

{% include alerts/warning.html body="Danger, danger Will Robinson." %}

Figures, with Images or Other Graphics

Here is how we include the CloudForest stack image in the overview post:

<div class="figure" id="overview">
	<img id="figure" src="/assets/images/overview/overview.png"/>
	<div class="figure-caption">
		Technologies and their relationships in a 
		running <code>CloudForest</code> platform.
	</div>
</div>

This is what actually renders:

Technologies and their relationships in a running CloudForest platform.

Any div with class figure is processed by some javascript when the page loads. A named anchor is inserted ahead of the “image”, which is just any child of that class-figure div with the id figure. It could be an img, svg, div, or canvas. The caption, if any, is whatever is included in a child div with class figure-caption. The script numbers the figures, and puts the figure number ahead of any caption that is provided. You can also reference figures, with (in this case) [](#overview) which renders as using the automatically generated number. You can put anything, or nothing, inside the [] here, it will get overwritten. But you have to reference the class-figure div id as the internal href.

Endnotes

You can include endnotes that get automatically formatted when a page loads by wrapping them in a <div> tag with the class endnote. If you are writing in markdown, you have to put spacing in between the relevant text and the note:

This is text that has a note at the end. 

<div class="endnote">
	This is an endnote.
</div>

And the next paragraph starts here. 

The spacing in between the preceeding text and the note will automatically get removed. The above markdown/html renders as follows: This is text that has a note at the end.

This is an endnote.

And the next paragraph starts here.

If you need to remove the spacing after the endnote as well, for an endnote inside a paragraph, just include nobreak in the class:

This is some text that requires a note. 

<div class="endnote nobreak">
	This is an "internal" endnote. 
</div>

The paragraph will continue, not end, here. 

The above markdown/html renders as follows: This is some text that requires a note at the end.

This is an "internal" endnote.

The paragraph will continue, not end, here.

Was this page useful?   or