To write longer or more detailed snippets of code, it is often better to place them inside a code block. Code blocks allow you to use multiple lines, and markdown will render it inside its own box and with code type font. To achieve this, start your block with a line of three backticks. This signals to markdown that you are creating a code block. Default site description. Markdown 不是要來取代 HTML，甚至也沒有要和它相似，它的語法種類不多，只和 HTML 的一部分有關係，. A list item with a blockquote: This is a blockquote inside a list item. เพิ่มการโต้ตอบของรหัส R ให้มากขึ้นด้วย R Markdown และ runtime Shiny. The 'Inline HTML' section of the documentation, markdown syntax, states that your html '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'.

1. Redcarpet Html Inside Markdown
2. Html Inside Markdown Table
3. Html Inside Markdown File
4. Html Inside Markdown File
5. Html Inside Markdown Tag
6. Using Html Inside Markdown
7. Html Vs Markdown

Markdown is a convenient HTML-focused shorthand syntax for formatting content such as documentation and blog articles, but it lacks basic features for image formatting, such as alignment and sizing.This post presents a variety of ways to format images with Markdown, from brute force to proprietary syntax extensions, unwise hacks, and everything in between.

Here’s how you insert an image in Markdown:

That is, Markdown allows you to specify an <img> tag with src, alt, and title attributes in HTML.Standard Markdown doesn’t offer anything beyond this, but it’s very common for websites to need width, height, and CSS class attributes as well.

The rest of this post is dedicated to various solutions to these shortcomings.To motivate this discussion, I’ll use the example of a large image that should be displayed at a smaller size.

For example,

I won’t show you how to add alignment, floating, or padding—but my sizing example will suffice, because once you know how to change an image’s size, you’ll know how to do other things too.I’ll show you the best solutions first, and the undesirable ones last.

Use Standard HTML

Markdown was originally designed for HTML authoring, and permits raw HTML anywhere, anytime.As such, the most straightforward solution is simply to use HTML with the desired attributes:

This works, and gives you unrestrained control over the resulting HTML.But Markdown is appealing for its simplicity, unlike HTML that’s cluttered with messy markup.Thus, many people dislike this solution because it defeats the purpose of Markdown.

Use CSS And Special URL Parameters

In general, the best way to style images is with CSS.Modern CSS syntax can select elements based on the values of their attributes, so one way to apply CSS rules is to encode extra information into Markdown’s standard src attribute.In this section I’ll discuss these possibilities.Later I’ll show you some undesirable CSS-related techniques too.

There are two places in a URL that you can overload to carry information that CSS can use: the URL fragment, and URL query parameters.

The URL fragment is the part that comes after the # character.When it’s used in a website’s URL, it can scroll the page to bring a desired part of the content into view, but you can add it to images, too.When you do that, it essentially does nothing as far as the browser is concerned, and a typical user will never see it in the browser’s address bar either.But it’s useful for our styling needs.Here we’ll add a thumbnail fragment to the image’s source URL:

This information is kept entirely client-side, and browsers don’t transmit this part of the URL to the server when they request content.However, CSS and JavaScript can read the fragment and use it.Here’s how to write a CSS selector that will match images with this “thumbnail” information in the URL:

The *= selector syntax matches if #thumbnail appears anywhere in the src attribute.You could also anchor the matching to the end of the URL with $='#thumbnail'.

Redcarpet Html Inside Markdown

This permits encoding only a single value into the URL, but you can modify this technique to add several.CSS also has a ~= selector, which matches if the specified value appears exactly in the attribute’s value, as a space-delimited “word,” so to speak.This lets you simulate combining multiple “classes” in the URL fragment:

Now you can target these pseudo “class” names from CSS:

An equivalent way to encode a space into a URL is with the %20 URL encoding, but I’ve found that this doesn’t work¹ in the Blackfriday Markdown processor with the technique I showed here:

Naturally, you can pick different ways to structure values, such as using a key=value syntax or whatever suits your purposes.Depending on what you prefer, you can use any of the CSS selector syntaxes that works well for you.

Another alternative is to use ordinary URL query parameters, the part that comes after the question-mark:

This will work, and you can use the same types of CSS selectors to apply styling to the resulting image.

However, in my opinion this is slightly less desirable, because query parameters are meant to transmit information to the server.The browser will include the parameters in the request, and there could be other disadvantages, such as preventing the browser from caching the images for better performance.Overall I don’t see any advantages to query parameters, unless there’s some reason you can’t use the URL fragment.

Use CSS’s nth-child() Selectors

You can also use CSS selectors that will select images based on their position in the document.For example, if your blog’s main content is wrapped inside an article element, and you want to change the appearance of the image inside the third paragraph, you could write the following CSS:

This will work, but it’s tedious and requires article-specific <style> tags with custom CSS.And you’ll need to change the CSS if you change the article, for example adding another paragraph above the image.In general this technique will be a burden to maintain, and I don’t do it.

To learn more about this, take a look at the CSS nth-of-type and nth-child selectors.

Use Proprietary Markdown Extensions

The original Markdown spec isn’t formal, and implementations vary.Many Markdown processors extend the syntax to add richness and control to the output.From Pandoc to Kramdown and Github-Flavored Markdown (GFM), extra syntaxes abound.There’s very little standardization, except for some consensus towards CommonMark and the gravitational pull of very popular libraries and processors.In this section I’ll explore some of these.

Some Markdown editors like Mou (a Mac writing app) have sizing extensions:

This example syntax is limited and isn’t widely supported.More common is the way Kramdown offers extensions to add attributes to block-level elements, including not only the height and width but CSS and other attributes:

Kramdown also supports one or more CSS classes with a shorthand syntax.Here’s an example of how to add class='thumbnail bordered' to the HTML after processing with Kramdown:

Pandoc offers a relative width specification, which works not only for HTML output, but for other output formats such as ( LaTeX ) as well:

Some other Markdown flavors offer similar ways to add attributes, though the syntax may differ slightly.All of these, however, extend the basic Markdown syntax in ways that may be incompatible.And some rumored support for extended syntax simply doesn’t exist; for example, I’ve seen references to nonexistent extensions in the blackfriday Markdown processor, which Hugo uses.

Use Wrapper HTML Tags

Another technique is to put an HTML tag around the <img> tag, like this:

Unfortunately, standard Markdown doesn’t process and convert the text inside of tags such as the <div>; as soon as it sees raw HTML it simply outputs it verbatim until the tags are closed again.This approach will work only with processors that support Markdown syntax extensions such as Markdown Extra.In Hugo, using Blackfriday, the resulting output is simply

Use Processor Hacks That Markdown Editors Ignore

Some users like to edit in a WYSIWYG editor such as Mou, but use a system such as Hugo to render the final Markdown into HTML for publication.Hugo has special processors that can add features to the output, such as brace-delimited shortcodes, which Mou doesn’t understand.

You can take advantage of this to inject content that overflows the alt attribute.The trick is to make the shortcode output an extra closing quote at the beginning of its output, emit the desired HTML attributes but omit the closing quote, and let the Markdown processor supply that.The benefit is that your editor will ignore the markup it doesn’t recognize, so it doesn’t disrupt your editing workflow.I don’t think this is better than the alternatives myself, but I mention it for completeness.

Abuse Image Attributes As CSS Selector Targets

In addition to the URL fragment as discussed previously, modern CSS syntax can select values of the alt and title attributes that standard Markdown supports.In this section I’ll discuss each of these possibilities, although I discourage their use.

Many Markdown users are only aware of the standard syntax’s support for the alt attribute, and don’t add titles to their images.In fact, many don’t even add alt text:

This makes it seem as though the alt text is undeveloped real estate that could be repurposed, for example adding the pseudo-equivalent of a “thumbnail” CSS class.Here’s how you might attempt to do that:

The corresponding CSS to select and format this image could be

Technically, this will work, but it’s not good for accessibility.Users who are using a screen reader or other accessibility aid will gain no benefit, and will suffer due to the lack of helpful information and the presence of misleading data in places it’s not intended to be.I discourage this practice.

A variation I’ve seen is to append, rather than replace, the alt text, using syntaxes such as the following examples:

Those examples can be paired with a CSS selector that matches the end of the attribute, such as img[alt$='-thumbnail'].These are perhaps less offensive than replacing the alt text entirely, but I still discourage this because there are better ways.

A variant of this approach, which has a roughly equivalent impact on accessibility, is to overload the title attribute with formatting instructions:

This can be selected from CSS as follows:

Again, I want to emphasize that this approach is not better than misusing the alt attribute.You should use URL fragments or URL query parameters as discussed earlier, instead of hijacking the image’s alt text or title.

On the other hand, if you want to write custom CSS per-article and use the CSS selector to target the image’s real alt text or title, that’s perfectly fine.In fact this is probably easier to maintain than nth-child selectors:

The demos in this page use the actual markup in the code listings. You can viewthe page source or look at the file in my Github repoto see the original markup in HTML and/or Markdown formats.

1. Thanks to a reader who pointed out that Markdown implementations vary widely in how they encode or interpret spaces. The technique as shown in this article doesn’t work with Grav, which needs spaces encoded as %20. This thread on StackOverflow has more information. ^[return]

Markdown support was introduced in doxygen version 1.8.0. It is a plain text formatting syntax written by John Gruber, with the following underlying design goal:

The design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown's syntax is the format of plain text email.

In the next section the standard Markdown features are briefly discussed. The reader is referred to the Markdown site for more details.

Some enhancements were made, for instance PHP Markdown Extra, and GitHub flavored Markdown. The section Markdown Extensions discusses the extensions that doxygen supports.

Finally section Doxygen specifics discusses some specifics for doxygen's implementation of the Markdown standard.

Paragraphs

Even before doxygen had Markdown support it supported the same way of paragraph handling as Markdown: to make a paragraph you just separate consecutive lines of text by one or more blank lines.

An example:

Headers

Just like Markdown, doxygen supports two types of headers

Level 1 or 2 headers can be made as the follows

A header is followed by a line containing only ='s or -'s. Note that the exact amount of ='s or -'s is not important as long as there are at least two.

Alternatively, you can use #'s at the start of a line to make a header. The number of #'s at the start of the line determines the level (up to 6 levels are supported). You can end a header by any number of #'s.

Here is an example:

Block quotes

Block quotes can be created by starting each line with one or more >'s, similar to what is used in text-only emails.

Lists and code blocks (see below) can appear inside a quote block. Quote blocks can also be nested.

Note that doxygen requires that you put a space after the (last) > character to avoid false positives, i.e. when writing

the second line will not be seen as a block quote.

Lists

Simple bullet lists can be made by starting a line with -, +, or *.

List items can span multiple paragraphs (if each paragraph starts with the proper indentation) and lists can be nested. You can also make a numbered list like so

Make sure to also read Lists Extensions for doxygen specifics.

Code Blocks

Preformatted verbatim blocks can be created by indenting each line in a block of text by at least 4 extra spaces

Doxygen will remove the mandatory indentation from the code block. Note that you cannot start a code block in the middle of a paragraph (i.e. the line preceding the code block must be empty).

See section Code Block Indentation for more info how doxygen handles indentation as this is slightly different than standard Markdown.

Horizontal Rulers

A horizontal ruler will be produced for lines containing at least three or more hyphens, asterisks, or underscores. The line may also include any amount of whitespace.

Examples:

Note that using asterisks in comment blocks does not work. See Use of asterisks for details.
Note that when using hyphens and the previous line is not empty you have to use at least one whitespace in the sequence of hyphens otherwise it might be seen as a level 2 header (see Headers).

Emphasis

To emphasize a text fragment you start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis.

Examples:

See section Emphasis and strikethrough limits for more info how doxygen handles emphasis / strikethrough spans slightly different than standard / Markdown GitHub Flavored Markdown.

Strikethrough

To strikethrough a text fragment you start and end the fragment with two tildes.

Examples:

See section Emphasis and strikethrough limits for more info how doxygen handles emphasis / strikethrough spans slightly different than standard Markdown / GitHub Flavored Markdown.

code spans

To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks, code spans appear inline in a paragraph. An example:

To show a literal backtick or single quote inside a code span use double backticks, i.e.

See section Code Spans Limits for more info how doxygen handles code spans slightly different than standard Markdown.

Links

Doxygen supports both styles of make links defined by Markdown: inline and reference.

For both styles the link definition starts with the link text delimited by [square brackets].

Inline Links

For an inline link the link text is followed by a URL and an optional link title which together are enclosed in a set of regular parenthesis. The link title itself is surrounded by quotes.

Examples:

In addition doxygen provides a similar way to link a documented entity:

Reference Links

Instead of putting the URL inline, you can also define the link separately and then refer to it from within the text.

The link definition looks as follows:

Instead of double quotes also single quotes or parenthesis can be used for the title part.

Once defined, the link looks as follows

If the link text and name are the same, also

or even

can be used to refer to the link. Note that the link name matching is not case sensitive as is shown in the following example:

Link definitions will not be visible in the output.

Like for inline links doxygen also supports @ref inside a link definition:

Images

Markdown syntax for images is similar to that for links. The only difference is an additional ! before the link text.

Examples:

Also here you can use @ref to link to an image:

The caption text is optional.

Automatic Linking

To create a link to an URL or e-mail address Markdown supports the following syntax:

Note that doxygen will also produce the links without the angle brackets.

Table of Contents

Doxygen supports a special link marker [TOC] which can be placed in a page to produce a table of contents at the start of the page, listing all sections.

Note that using [TOC] is the same as using a tableofcontents command.

Note that the TOC_INCLUDE_HEADINGS has to be set to a value > 0 otherwise no table of contents is shown when using Markdown Headers.

Tables

Of the features defined by 'Markdown Extra' is support for simple tables:

A table consists of a header line, a separator line, and at least one row line. Table columns are separated by the pipe (|) character.

Here is an example:

which will produce the following table:

Column alignment can be controlled via one or two colons at the header separator line:

which will look as follows:

Additionally, column and row spans are supported. Using a caret ('^') in a cell indicates that the cell above should span rows. Sequences of carets may be used for any number of row spans. For example:

which will look as follows:

Column spans are supported by means of directly adjacent vertical bars ('|'). Each additional vertical bar indicates an additional column to be spanned. To put it another way, a single vertical bar indicates a single column span, two vertical bars indicates a 2 columns span, and so on. For example:

which will look as follows:

For more complex tables in doxygen please have a look at: Including tables

Fenced Code Blocks

Another feature defined by 'Markdown Extra' is support for fenced code blocks:

A fenced code block does not require indentation, and is defined by a pair of 'fence lines'. Such a line consists of 3 or more tilde (~) characters on a line. The end of the block should have the same number of tildes. Here is an example:

By default the output is the same as for a normal code block.

For languages supported by doxygen you can also make the code block appear with syntax highlighting. To do so you need to indicate the typical file extension that corresponds to the programming language after the opening fence. For highlighting according to the Python language for instance, you would need to write the following:

which will produce:

and for C you would write:

which will produce:

The curly braces and dot are optional by the way.

Another way to denote fenced code blocks is to use 3 or more backticks (```):

Html Inside Markdown Table

Header Id Attributes

Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.

PHP Markdown Extra allows you to label a header by adding the following to the header

To link to a section in the same comment block you can use

to link to a section in general, doxygen allows you to use @ref

Note this only works for the headers of level 1 to 4.

Even though doxygen tries to following the Markdown standard as closely as possible, there are couple of deviation and doxygen specifics additions.

Including Markdown files as pages

Doxygen can process files with Markdown formatting. For this to work the extension for such a file should be .md or .markdown (see EXTENSION_MAPPING if your Markdown files have a different extension, and use md as the name of the parser). Each file is converted to a page (see the page command for details).

By default the name and title of the page are derived from the file name. If the file starts with a level 1 header however, it is used as the title of the page. If you specify a label for the header (as shown in Header Id Attributes) doxygen will use that as the page name.

If the label is called index or mainpage doxygen will put the documentation on the front page (index.html).

Here is an example of a file README.md that will appear as the main page when processed by doxygen:

If a page has a label you can link to it using @ref as is shown above. To refer to a markdown page without such label you can simple use the file name of the page, e.g.

Treatment of HTML blocks

Markdown is quite strict in the way it processes block-level HTML:

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.

Doxygen does not have this requirement, and will also process Markdown formatting inside such HTML blocks. The only exception is <pre> blocks, which are passed untouched (handy for ASCII art).

Doxygen will not process Markdown formatting inside verbatim or code blocks, and in other sections that need to be processed without changes (for instance formulas or inline dot graphs).

Code Block Indentation

Markdown allows both a single tab or 4 spaces to start a code block. Since doxygen already replaces tabs by spaces before doing Markdown processing, the effect will only be same if TAB_SIZE in the configuration file has been set to 4. When it is set to a higher value spaces will be present in the code block. A lower value will prevent a single tab to be interpreted as the start of a code block.

With Markdown any block that is indented by 4 spaces (and 8 spaces inside lists) is treated as a code block. This indentation amount is absolute, i.e. counting from the start of the line.

Since doxygen comments can appear at any indentation level that is required by the programming language, it uses a relative indentation instead. The amount of indentation is counted relative to the preceding paragraph. In case there is no preceding paragraph (i.e. you want to start with a code block), the minimal amount of indentation of the whole comment block is used as a reference.

In most cases this difference does not result in different output. Only if you play with the indentation of paragraphs the difference is noticeable:

In this case Markdown will put the word code in a code block, whereas doxygen will treat it as normal text, since although the absolute indentation is 4, the indentation with respect to the previous paragraph is only 1.

Note that list markers are not counted when determining the relative indent:

For Item1 the indentation is 4 (when treating the list marker as whitespace), so the next paragraph 'More text...' starts at the same indentation level and is therefore not seen as a code block.

Emphasis and strikethrough limits

Unlike standard Markdown and Github Flavored Markdown doxygen will not touch internal underscores or stars or tildes, so the following will appear as-is:

Furthermore, a * or _ only starts an emphasis and a ~ only starts a strikethrough if

• it is followed by an alphanumerical character, and
• it is preceded by a space, newline, or one the following characters <{([,:;

An emphasis or a strikethrough ends if

Html Inside Markdown File

• it is not followed by an alphanumerical character, and
• it is not preceded by a space, newline, or one the following characters ({[<=+-@

Lastly, the span of the emphasis or strikethrough is limited to a single paragraph.

Code Spans Limits

Note that unlike standard Markdown, doxygen leaves the following untouched.

In other words; a single quote cancels the special treatment of a code span wrapped in a pair of backtick characters. This extra restriction was added for backward compatibility reasons.

In case you want to have single quotes inside a code span, don't use one backtick but two backticks around the code span.

Lists Extensions

With Markdown two lists separated by an empty line are joined together into a single list which can be rather unexpected and many people consider it to be a bug. Doxygen, however, will make two separate lists as you would expect.

Example:

With Markdown the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. I.e. standard Markdown treats the following as one list with 3 numbered items:

Doxygen however requires that the numbers used as marks are in strictly ascending order, so the above example would produce 3 lists with one item. An item with an equal or lower number than the preceding item, will start a new list. For example:

will produce:

1. Item1 of list 1
2. Item2 of list 1

1. Item1 of list 2
2. Item2 of list 2

Historically doxygen has an additional way to create numbered lists by using -# markers:

Use of asterisks

Special care has to be taken when using *'s in a comment block to start a list or make a ruler.

Doxygen will strip off any leading *'s from the comment before doing Markdown processing. So although the following works fine

When you remove the leading *'s doxygen will strip the other stars as well, making the list disappear!

Rulers created with *'s will not be visible at all. They only work in Markdown files.

Limits on markup scope

To avoid that a stray * or _ matches something many paragraphs later, and shows everything in between with emphasis, doxygen limits the scope of a * and _ to a single paragraph.

For a code span, between the starting and ending backtick only two new lines are allowed.

Also for links there are limits; the link text, and link title each can contain only one new line, the URL may not contain any newlines.

Html Inside Markdown File

When doxygen parses the source code it first extracts the comments blocks, then passes these through the Markdown preprocessor. The output of the Markdown preprocessing consists of text with special commands and HTML commands. A second pass takes the output of the Markdown preprocessor and converts it into the various output formats.

Html Inside Markdown Tag

During Markdown preprocessing no errors are produced. Anything that does not fit the Markdown syntax is simply passed on as-is. In the subsequent parsing phase this could lead to errors, which may not always be obvious as they are based on the intermediate format.

Using Html Inside Markdown

To see the result after Markdown processing you can run doxygen with the -d Markdown option. It will then print each comment block before and after Markdown processing.

Html Vs Markdown

Go to the next section or return to the index.