Powered by GitBook

CoIDE Manual V2.0

CooCox

CoIDE Markdown Formatting Syntax

Comments: This is an introduction of the Markdown formatting syntax involved in CoIDE component document. CoIDE Markdown editor supports all legal Markdown characters.

Note: If you are not familiar with the Markdown formatting Syntax, the materials below will be of some help.

  1. Markdown Formatting Syntax Chinese edition | English edition
  2. Markdown Online Editor
  3. Markdown Quick Start Guide

FILE NAME

Doxygen will show the first first level header as the file name when parsing. To distinguish a file name from a header, we recommend you to write your file name like this.

Your File Name
=========

HEADERS

Headers use 1-5 hash characters at the start of the line, corresponding to header levels 1-5.

For example:

# This is an H1
## This is an H2
### This is an H3
#### This is an H4
##### This is an H5

Note: Headers above level 5 are supported but not recommended.

will produce:

This is an H1

This is an H2

This is an H3

This is an H4

This is an H5

EMPHASIS

To emphasize a text, wrap it with double asterisks.

For example:

**This is bold text**
*This is italic text*

will produce:

This is bold text
This is italic text

[NAME](URL "TITLE")
NAME is the link text, URL is where you want the link to point, and TITLE is a prompt text for the link.

Note: TITLE is an optional item. When a cursor is stayed on the link, the TITLE text, if any, will prompt.

For example:

[CooCox](http://www.coocox.org/images/logo.jpg )
[CooCox](http://www.coocox.org/images/logo.jpg "CooCox")

will produce:

CooCox
CooCox

IMAGES

With the plain syntax of Doxygen and Markdown, you can easily insert images to your document. Below are detailed steps of how to insert an image and some operation suggestions.

There are two styles of images: inline and reference.
Reference-style images are located on web server, while inline-style images are located locally or quoted by relative paths. They use the same syntax as below:

![NAME](URL "TITLE")

Among which:

  1. NAME is an image ID to help recognize the image
  2. URL is the link to the image, which can be a relative or absolute path
  3. TITLE is a prompt text for the image. When a cursor is stayed on the image, the TITLE text, if any, will prompt.

Here comes an example of how to insert an image.

Insert a reference-style image with an URL:

Insert a reference-style image with an URL: http://www.coocox.org/images/logo.jpg

It looks like this:

![CooCox](http://www.coocox.org/images/logo.jpg )

and will produce:
CooCox

Insert an inline-style image

Use the image name as the relative path directly.

Assume that there is already an image named CooCox_CooCox_Logo_0000 in the Component Doc directory, you can use the local image directly like this:

![CooCox](CooCox_CooCox_Logo_0000.gif "CooCox")

Notes:

When inserting inline-style images, Doxygen will first copy the images from different sub-directories to the HTML output directory, and the HTML will quote one level relative paths. When there are too many image resources, image name conflict may happen. To avoid such kind of problem, we set a rule as below to name the images:

Author+Component name+Functionality+Index number

An index number is a decimal double figure specified by users, ranging from 0 to 99.

LISTS

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Ordered lists use numbers followed by periods and list items with a space in between:
[Number][.][Space][List item]

Unordered lists use asterisks followed by a space and then list items: [*][Space][List item]

Note: A blank line should be used to separate lists in different paragraphs

For example:

An ordered list:

1. Item A
2. Item B
3. Item C

A disordered list:

* Item A
* Item B
* Item C

A mix with ordered and disordered list:

1. Item A
    * Item 1A
    * Item 1B
    * Item 1C
2. Item B
    * Item 2A
    * Item 2B
    * Item 2C
3. Item C
    * Item 3A
    * Item 3B
    * Item 3C

Will produce:

An ordered list:

  1. Item A
  2. Item B
  3. Item C

A disordered list:

  • Item A
  • Item B
  • Item C

A mix with ordered and disordered list:

  1. Item A
    • Item 1A
    • Item 1B
    • Item 1C
  2. Item B
    • Item 2A
    • Item 2B
    • Item 2C
  3. Item C
    • Item 3A
    • Item 3B
    • Item 3C

Note: In a nested list, each subsequent item should be indented by 4 spaces

BLOCKQUOTES

Put the > followed by a space before the first line of a paragraph.
Note: Blockquotes can be nested (i.e. a blockquote-in-a-blockquote), and can contain other Markdown elements, including headers, lists, and code blocks

For example:

> Email-style angle brackets  
> are used for blockquotes.

> > And, they can be nested.

> #### Headers in blockquotes
> 
> * You can quote a list.
> * Etc.

Will produce:

Email-style angle brackets
are used for blockquotes.

And, they can be nested.

Headers in blockquotes

  • You can quote a list.
  • Etc.

CODE BLOCKS

  1. Insert at least 3 wave lines in a row in the line below the code block.
  2. followed by the programming language type, {.programming language type}
  3. followed by the code block
  4. followed by a blank line and then the line of as many wave lines as the first line.

Cautions:

  1. The number of wave lines in the first and last line should be the same
  2. The programming language type is an optional item
  3. All comments in the code block should be marked by "//" characteristic due to Doxygen syntax

If there are lots of comments for the code, you can consider putting them in a separate file, and quote the file in Readme.md file.

For example:

~~~~~~~~~~{.c}
// Hello, this is a function
printf("Hello world");
~~~~~~~~~~

is used to insert the code printf ("Hello world") written in C and highlight it.

Will produce:

printf("Hello world");

TEXT-FORMATTING

Note: It's used to display some mark or code in a text format

Wrap the mark or code with ', and wrap them with spaces.

For example:

Example: '<pre>' is a plain word

Will produce:

Example: <pre> is a plain word

HORIZONTAL RULES

Use three or more underscores, and wrap them with blank lines.

For example:

Press ENTER
---
Press ENTER

Will produce:

FORCED LINE FEED

Markdown syntax forces line feed via adding over two spaces at the end of line. But Doxygen will remove the spaces in preprocessing stage, and turn Markdown tags to internal tags, and then complie them together with source code and generate a document . Therefore, the standard Markdown way won't take effect, we can only force the line feed by the following inelegent ways:

  1. <br>
  2. \n

Note: You can force line feed at any place you want, including within a table.

INLINE HTML

Markdown supports inline HTML, which allows you to create documents in any style you want. Here is one thing you need to pay special attention to:

The only restrictions Markdown syntax has for inserting HTML are:

Block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces.

Good news is that there is no such restriction as above in Doxygen. You can even insert Markdown formatted content in HTML blocks.

Doxygen won't process corresponding block contents in below conditions:

  1. Block wrapped by <pre>
  2. Block wrapped by \verbatim
  3. Code block

Note:Although Doxygen won't process content in code block, it will remove the indented spaces and make the code look disordered. If you need to insert preformatted code in comment or Markdown, it's best to use the <pre> tag or directly insert a code block.

INSERT A PREFORMATTED TEXT

You can insert a preformatted text to Markdown syntax by 4 spaces indentation.

REFERENCE