diff --git a/guide/src/README.md b/guide/src/README.md index ac6f48e768..7bbfd9958c 100644 --- a/guide/src/README.md +++ b/guide/src/README.md @@ -18,13 +18,6 @@ In addition to the above features, mdBook also has a Rust [API](https://docs.rs/ write your own preprocessor or renderer, as well as incorporate mdBook features into other applications. The [For Developers](for_developers) section of this guide contains more information and some examples. -## Markdown - -mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/) -specification. You can take a quick [tutorial](https://commonmark.org/help/tutorial/), -or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. For a more in-depth experience, check out the -[Markdown Guide](https://www.markdownguide.org). - ## Contributing mdBook is free and open source. You can find the source code on diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 37e9fca015..181d797284 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -22,6 +22,7 @@ - [Editor](format/theme/editor.md) - [MathJax Support](format/mathjax.md) - [mdBook-specific features](format/mdbook.md) + - [Markdown](format/markdown.md) - [Continuous Integration](continuous-integration.md) - [For Developers](for_developers/README.md) - [Preprocessors](for_developers/preprocessors.md) diff --git a/guide/src/format/images/rust-logo-blk.svg b/guide/src/format/images/rust-logo-blk.svg new file mode 100644 index 0000000000..1a6c762d4e --- /dev/null +++ b/guide/src/format/images/rust-logo-blk.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/guide/src/format/markdown.md b/guide/src/format/markdown.md new file mode 100644 index 0000000000..74ecaf56cb --- /dev/null +++ b/guide/src/format/markdown.md @@ -0,0 +1,107 @@ +# Markdown + +mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/) +specification. You can take a quick [tutorial](https://commonmark.org/help/tutorial/), +or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. A complete Markdown overview is out of scope for +this documentation, but below is a high level overview of some of the basics. For a more in-depth experience, check out the +[Markdown Guide](https://www.markdownguide.org). + +## Text and Paragraphs + +Text is rendered relatively predictably: + +```markdown +Here is a line of text. + +This is a new line. +``` + +Will look like you might expect: + +Here is a line of text. + +This is a new line. + +## Headings + +Headings use the `#` marker and should be on a line by themselves. More `#` mean smaller headings: + +```markdown +### A heading + +Some text. + +#### A smaller heading + +More text. +``` + +### A heading + +Some text. + +#### A smaller heading + +More text. + +## Lists + +Lists can be unordered or ordered. Ordered lists will order automatically: + +```markdown +* milk +* eggs +* butter + +1. carrots +1. celery +1. radishes +``` + +* milk +* eggs +* butter + +1. carrots +1. celery +1. radishes + +## Links + +Linking to a URL or local file is easy: + +```markdown +Use [mdBook](https://github.com/rust-lang/mdBook). + +Read about [mdBook](mdBook.md). + +A bare url: . +``` + +Use [mdBook](https://github.com/rust-lang/mdBook). + +Read about [mdBook](mdBook.md). + +A bare url: . + +## Images + +Including images is simply a matter of including a link to them, much like in the _Links_ section above. The following markdown +includes the Rust logo SVG image found in the `images` directory at the same level as this file: + +```markdown +![The Rust Logo](images/rust-logo-blk.svg) +``` + +Produces the following HTML when built with mdBook: + +```html +

The Rust Logo

+``` + +Which, of course displays the image like so: + +![The Rust Logo](images/rust-logo-blk.svg) + + +See the [Markdown Guide Basic Syntax](https://www.markdownguide.org/basic-syntax/) document for more.