1# Markdown Quickstart Template 2 3## Introduction and Quickstart 4 5This document is meant to get you writing documentation as fast as possible 6even if you have no previous experience with Markdown. The goal is to take 7someone in the state of "I want to write documentation and get it added to 8LLVM's docs" and turn that into useful documentation mailed to llvm-commits 9with as little nonsense as possible. 10 11You can find this document in `docs/MarkdownQuickstartTemplate.md`. You 12should copy it, open the new file in your text editor, write your docs, and 13then send the new document to llvm-commits for review. 14 15Focus on *content*. It is easy to fix the Markdown syntax 16later if necessary, although Markdown tries to imitate common 17plain-text conventions so it should be quite natural. A basic knowledge of 18Markdown syntax is useful when writing the document, so the last 19~half of this document (starting with [Example Section](#example-section)) gives examples 20which should cover 99% of use cases. 21 22Let me say that again: focus on *content*. But if you really need to verify 23Sphinx's output, see `docs/README.txt` for information. 24 25Once you have finished with the content, please send the `.md` file to 26llvm-commits for review. 27 28## Guidelines 29 30Try to answer the following questions in your first section: 31 321. Why would I want to read this document? 33 342. What should I know to be able to follow along with this document? 35 363. What will I have learned by the end of this document? 37 38Common names for the first section are `Introduction`, `Overview`, or 39`Background`. 40 41If possible, make your document a "how to". Give it a name `HowTo*.md` 42like the other "how to" documents. This format is usually the easiest 43for another person to understand and also the most useful. 44 45You generally should not be writing documentation other than a "how to" 46unless there is already a "how to" about your topic. The reason for this 47is that without a "how to" document to read first, it is difficult for a 48person to understand a more advanced document. 49 50Focus on content (yes, I had to say it again). 51 52The rest of this document shows example Markdown markup constructs 53that are meant to be read by you in your text editor after you have copied 54this file into a new file for the documentation you are about to write. 55 56## Example Section 57 58Your text can be *emphasized*, **bold**, or `monospace`. 59 60Use blank lines to separate paragraphs. 61 62Headings (like `Example Section` just above) give your document its 63structure. 64 65### Example Subsection 66 67Make a link [like this](https://llvm.org/). There is also a more 68sophisticated syntax which [can be more readable] for longer links since 69it disrupts the flow less. You can put the `[link name]: <URL>` block 70pretty much anywhere later in the document. 71 72[can be more readable]: http://en.wikipedia.org/wiki/LLVM 73 74Lists can be made like this: 75 761. A list starting with `[0-9].` will be automatically numbered. 77 781. This is a second list element. 79 80 1. Use indentation to create nested lists. 81 82You can also use unordered lists. 83 84* Stuff. 85 86 + Deeper stuff. 87 88* More stuff. 89 90#### Example Subsubsection 91 92You can make blocks of code like this: 93 94``` 95int main() { 96 return 0; 97} 98``` 99 100As an extension to markdown, you can also specify a highlighter to use. 101 102``` C++ 103int main() { 104 return 0; 105} 106``` 107 108For a shell session, use a `console` code block. 109 110```console 111$ echo "Goodbye cruel world!" 112$ rm -rf / 113``` 114 115If you need to show LLVM IR use the `llvm` code block. 116 117``` llvm 118define i32 @test1() { 119entry: 120 ret i32 0 121} 122``` 123 124Some other common code blocks you might need are `c`, `objc`, `make`, 125and `cmake`. If you need something beyond that, you can look at the [full 126list] of supported code blocks. 127 128[full list]: http://pygments.org/docs/lexers/ 129 130However, don't waste time fiddling with syntax highlighting when you could 131be adding meaningful content. When in doubt, show preformatted text 132without any syntax highlighting like this: 133 134 . 135 +:. 136 ..:: :: 137 .++:+:: ::+:.:. 138 .:+ : 139 ::.::..:: .+. 140 ..:+ :: : 141 ......+:. .. 142 :++. .. : 143 .+:::+:: : 144 .. . .+ :: 145 +.: .::+. 146 ...+. .: . 147 .++:.. 148 ... 149 150##### Hopefully you won't need to be this deep 151 152If you need to do fancier things than what has been shown in this document, 153you can mail the list or check the [Common Mark spec]. Sphinx specific 154integration documentation can be found in the [recommonmark docs]. 155 156[Common Mark spec]: http://spec.commonmark.org/0.28/ 157[recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html 158