-
Notifications
You must be signed in to change notification settings - Fork 4
Coding the Docs
This section describes how to format various aspects of the devportal docs.
- Alerts
- Bold
- Definition Lists
- Examples
- Hover Definitions
- HTML
- Images
- Italics
- Links
- Lists
- Page Navigation
- Tables
- Variables
Alerts are things like notes, tips, and other important messages. Notes reside in their own code block that looks like this:
{% include note.html content="This is a note." %}
You can change the style of the note by changing which file is included. For example, the note above will include the word Note. But if you wanted it to be a tip, include tip.html. Or, if it's super important, use important.html.
You can't use markdown in alerts. If you need to, you can use HTML though.
You can use either two underscores or two asterisks. In Atom, the two asterisks approach works well because you can double-click the word and type an asterisk to automatically enclose it.
You can use either one underscore or one asterisk. In Atom, the one underscore approach works well because you can double-click the word and type an underscore to automatically enclose it.
- Inline use tics, like this: `Code`
- Code blocks use three tics (fences) at the top and the bottom, with empty lines before and after.
- Add highlights to the code by specifying languages: json, bash (for cURL examples), and js.
Make sure JSON is indented properly and enclosed in JSON fences, like this:
```json
{
"level":"instance",
"vendorName":"<VENDOR_RESOURCE>",
"fields":[
{
"path":"<COMMON_RESOURCE_FIELD>",
"type":"<COMMON_RESOURCE_TYPE>",
"vendorPath":"<VENDOR_FIELD>",
"vendorType":"<VENDOR_TYPE>"
}
]
}```
Lastly, to line up a code block in a list, select all lines in the block and tab twice. create an empty line. Add the JSON within the JSON fence. Select the entire object and indent two times. This should get it to line up with the numbers.
Definition lists are a special kind of list to use in conjunction with glossary terms. See an example in Common Resources.
Here's how it's done:
<dl>
<dt id="Common-resource">common resource</dt>
<dd>{{site.data.glossary.common_resource}}</dd>
<dt id="normalized">normalize</dt>
<dd>{{site.data.glossary.normalize}} In relation to common resources, normalization is the transformation of related fields and objects in multiple element resources to a single definition of the field or object within a common resource.</dd>
</dl>
When adding examples to the docs, use camelCase.
👍 lastName. 👎 LASTNAME, LASTname, lastname
These are glossary terms where when you hover over the term, the definition appears. The definitions are stored in the glossary.yml file in the _data directory. The data looks like this:
common_resource: "An API resource that defines normalized fields for frequently used resources that you can use in place of specific elements to facilitate one-to-many integrations. You map fields from element resources to the common resource fields to create transformations."
To add a term, add code like this:
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.common_resource}}">common resource</a>
Where {{site.data.glossary.common_resource}} identifies the specific term.
HTML is ok throughout the devportal, but the general rule is to use HTML only if you must. Otherwise, use markdown. A few places where you'll have to use HTML:
Preferably, use SnagIt, reduce the size to 75% and ad a border. This is especially important if the screenshot does not already have a clear border. Otherwise, it can appear that there is no clear distinction between image and background.
Save images in one of two places:
-
If the image is not going to be reused anywhere else, save images in an img/ directory along with your content. For example, if you're working with the Foo element, the Foo directory contains files like index.md, events.md, and a directory called img. This helps make maintenance of the images easier than hosting them on individual Cloud App accounts.
-
If you will reuse the image via includes, add it to the assets/images directory in the most appropriate location.
It's easy!
Where the ! is required, text in the square brackets [ ] is the title of the image, and text in the parentheses ( ) is the link to the image. See the markdown reference for more.
If the image resides in the assets directory, use a path like /assets/img/<folder>/image.png
Also, to help images load more quickly, optimize them. See ImageOptim for some very simple instructions.
If you need to highlight anything in the image, just use a red rectangle shape.
You can use either one underscore or one asterisk. In Atom, the one underscore approach works well because you can double-click the word and type an underscore to automatically enclose it.
Liberally add links to other pages or even the web. Here are a few ways to add links. See the cheatsheet for more on links.
| Link | Info | Example |
|---|---|---|
| General Link Structure | Wrap words in brackets [] and the link in parentheses (). | [Link Name](uri) |
| Links internal to a page | Append a # and refer to the location in lower case, hyphenating multiple words. | [Page Navigation](#page-navigation) |
| Link to a page in the same directory | Use just the file name as HTML, not md. |
[Authenticate](authenticate.html) |
| Link to another page in devportal | Specify the part of the URL following developers.cloud-elements.com | [Hub API Docs](/hubs/hub-docs) |
Lists are easy, except when they are not. See the cheatsheet for the basics.
- Include a stem sentence before every list (except this one 😉 , like "To set something up:" or "We support the following authentication types:"
- Add an empty line between the stem sentence and the first list item.
- To add text between list items that is not itself a list item, such as a note or a result statement, add two tabs and add empty lines before and after.
- To add code between list items, see the Code entry.
- To create a list of headings at the top of the page, or a TOC, see Page Navigation.
Any page with more than two H2s should have page navigation. This is the "On this page" section that you can see here.
To add page navigation, include code like this:
{% include callout.html content="<strong>On this page</strong><br/><a href=#example>Example</a><br/><a href=#understanding-levels>Understanding Levels</a><br/><a href=#definitions>Definitions</a>" type="info" %}
- Add links to each H2.
- You must use HTML instead of markdown in this code.
- Links to headings should just include the # (
<a href=#example>)and the heading in lower case, with separate words joined by hyphens (<a href=#understanding-levels>. - Include empty lines before and after.
To create tables, just add this code which creates a two column table with a header.
| Heading | Heading |
| :------------- | :------------- |
| Body | Body |
UI Field names and other components (buttons, tabs, links). Use bold.
For code, use code formatting (tics, etc.)
The docs use a few different variables to make it easier to reuse content. These include:
- {{page.heading}} which is used mostly in the Element docs. When served, this is replaced by the contents of the heading parameter in the header at the top of the page.
- {{page.elementKey)) also mostly used in the element docs. It's used to replace the variable with the element key of the element.
- {{site.consols}} is used to refer to the Cloud Elements console. It's defined in the _config.yml file.