-
Notifications
You must be signed in to change notification settings - Fork 3
Markdown Guidelines
Markdown is a basic markup language with the goals of making text easy to write but also easy to read as simple plain text. But this same plain text can also be formatted nicely into HTML. It's similar and simpler than reStructuredText.
In addition to the The Markdown Guide and GitHub's Mastering Markdown, here are some extra notes to help make your Markdown shine, whether for wiki pages like this one, GitHub issue templates, project READMEs, and so forth.
In markup languages (and in English in general) there's the notion of inline markup versus block markup. Inline markup is like these words that are suddenly in boldface, or inline HTML tags like <span>
and <strong>
.
Whereas block markup is the fact that these are two paragraphs (two blocks), or block HTML tags like <div>
and <h2>
.
When writing in Markdown, you can preserve the semantic differences between inline and block markup by using the formatting appropriate to each. For example, do this ✅
## Describe the Bug
A clear and concise description of what the bug is.
Don't do this ❌
**Describe the Bug**
A clear and concise description of what the bug is.
The former uses an actual heading block element, while the latter abuses an inline boldface element.
Why do this? One tangible benefit is for accessibility: screen-readers use semantic structure to better present information for people with disabilities. For example, a screen reader can speak boldface text in an emphatic voice while keyboard shortcuts allow those with motor difficulties to navigate between headings. Using boldface as a heading defeats both of these assistive technologies.
Modern operating systems let you type emoji directly into your files and even at your terminal prompts.
For macOS users, press ⌃⌘Space and choose (or type a few characters to search) for the emoji or other character you want. Or choose "Emoji & Symbols" from the "Edit" menu of most apps.
For Windows users, press the Windows key and the period . or semicolon ; keys and then choose an emoji.
For various flavors of Linux, it … varies 😅. You can try right-clicking to get a context menu and choose "Insert Emoji" or try pressing ctrl and the period key.
Copyright © 2021-2024 California Institute of Technology.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.