https://github.com/smartdevicelink/sdl_markdown_spec
Specification writing documentation in DocDown
https://github.com/smartdevicelink/sdl_markdown_spec
Last synced: 4 months ago
JSON representation
Specification writing documentation in DocDown
- Host: GitHub
- URL: https://github.com/smartdevicelink/sdl_markdown_spec
- Owner: smartdevicelink
- Created: 2016-06-09T14:35:15.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2019-06-21T17:33:15.000Z (about 7 years ago)
- Last Synced: 2025-11-18T09:20:19.091Z (7 months ago)
- Homepage:
- Size: 57.6 KB
- Stars: 3
- Watchers: 6
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# DocDown Format
v 1.0
---
## Directory Structure
The repository will contain the following files at the root level:
- `docs` This folder will be the root of the documentation.
- `LICENSE` The license for the documentation
- `config.json` Navigation structure and optional repo configuration
#### config.json
This file contains a dictionary of all sections and classes contained in the repository, in the order in which they will appear on the developer portal. It also allows the option to override the default language and default asset directory.
#### /docs
The root level of /docs contains an “assets” directory for storage of global assets, an “index.md” file for root-level content, and individual directories for each section or class. Directories can contain spaces.
Each directory in /docs can contain an “index.md” which contains the documentation in the Markdown format as described below.
In addition to the Markdown file, assets like code samples, tables, and images, can be stored in an “assets” folder next to the index.md file. Supported files are listed in the [Importing Files](#importing-files) section.
When referencing assets, the parser will first look at the /assets directory at the same level as the “index.md” file. If the asset is not found, the parser will look up the directory tree until it reaches the global /assets directory. Assets cannot be shared across repositories.
#### Nesting
Maximum pages level in hierarchy is 2 only.
Example:
```
docs \
Level 1 \
index.md
level 2 \
index.md
level 2 \
index.md
...
level 1 \
index.md
...
```
## Basic Markdown Syntax
#### Page headers
###### H1
**NOTE**: H1 is reserved for page titles and shouldn’t be used in the documentation
`#`
###### H2
Page Section Titles
`##`
###### H3
Sub-Section Titles
`###`
###### H4
Chart Titles
`####`
###### H5
Notes, Chart Column Titles
`#####`
###### H6
Chart Row Titles
`######`
###### Header anchor
Each Header could be used as [anchor links](#anchor-links)
The rule for links is following:
- remove '.' (dots)
- replace ' ' (spaces) with '-' (hyphen)
- convert all upper case letters to lower case
Example:
```
## 4.1.4 Chapter 4.1.4 References
---
[link text](#--414--chapter-414-references)
```
#### Text Styling
###### Emphasis
`_emphasis_`, or `*emphasis*`
###### Strong
`__strong__`, or `**strong**`
###### Strikethrough
`~~strikethrough~~`
###### Inline Code
```
`code`
```
###### Block Code
> \`\`\`language
> Class = new className;
> \`\`\`
###### Blockquotes
Supports nested blockquotes
`>`
#### Lists
###### Unordered list
```
- List item 1
- List item 2
```
###### Ordered list
```
1. Item 1
1. Item 2
```
#### Links
###### Inline Link
`[link text](https://www.google.com)`
###### Inline Link + Title
`[link text](https://www.google.com “Title”)`
###### Reference Link
```
[link text][reference text]
---
[reference text]: https://www.google.com
```
###### Anchor links
`[link text](#achor)`
#### Images
###### Inline Image
``
###### Reference Image
```
![alt text][image]
---
[image]: https://google.com/image.png "Title Text"
```
#### Tables
###### Table Structure
```
| Header | Header 2 | Header 3 |
| ---------------- | ------------------ | ------------------ |
| cell content | cell content | cell content |
```
###### Center align column
```
| Header | Header 2 | Header 3 |
| :--------------: | ------------------ | ------------------ |
```
##### Right align column
```
| Header | Header 2 | Header 3 |
| ---------------: | ------------------ | ------------------ |
```
#### Page Elements
###### Horizontal Rule
`---`
###### Line Break
```
Line 1 text
Line 2 text
```
##### Paragraph Break
```
Line 1 text
Line 2 text
```
## Extended Markdown Syntax
#### Notes
###### Generic Note
Fenced by !!!. Supports inline markdown. Content can start on first line or new line. “NOTE” type is optional, as it is the default.
```
!!! NOTE
Content
!!!
```
###### Important Note
```
!!! IMPORTANT
Content
!!!
```
###### Developer Must
```
!!! MUST
Content
!!!
```
###### Developer May
```
!!! MAY
Content
!!!
```
###### Sequencing Charts
Link to Sequencing Chart
```
|||
Content
|||
```
## Links
###### Link to another class
`[link text][Class Name]` or
`[link text][parent/ClassName]`
Links without a leading slash are treated as links between documents by the parser. The parent directory can be included to handle namespace conflicts.
###### Link to a specific version
`[link text][version/ClassName]`
If omitted, the latest version is used for the link
###### Link to a specific constant in a class or method
`[link text][version/Class Name/constant]`
`[link text][version/Class Name/method]`
###### Link between platforms
`[link text][platform/version/Class Name/constant]`
Allows the link to traverse repos (linking iOS to Core). Version and Constant are optional.
## Document Metadata
A document can begin with a metadata section defined by “---” with keys and values as shown below:
```
---
key: value
key2: value2
---
```
## HTML
DocDown converts documents from Markdown into HTML, therefore most HTML tags are supported. Use HTML tags with caution as each template can render the them differently leading to unexpected outcomes.
## Language Support
Localization of files is handled by appending the language code to the file itself. Directories currently cannot be localized. The default language is `_en_us` and is optional. Assets can be localized as well, in the same fashion.
## Importing Files
External code snippets can be imported and will be parsed using their native language. CSV imports will create HTML tables from their content. The parser will look in the assets/ directory for all imported files.
`+++ file.m`
`+++ response.json` would import a JSON code snippet from `assests/response.json`.
Supported file types:
* JSON
* CSV
* HTML
* JS
* CSS
* Obj-C
* Swift
* Java
* C++