Amazon Kindle Scribe digital notebook with a 10 inch Paperwhite display
Still on my wishlist, but it is promising. The smaller kindles don't let me see enough of PDFs for technical sections.
Friday, February 16, 2024
Technical writers would agree that writing complex documentation with proper formatting can be tedious and time-consuming.
This in-depth guide provides a comprehensive set of markdown shortcuts that can help simplify and streamline documentation tasks for technical writers.
You'll learn markdown syntax for formatting text, creating code blocks, adding images and links, building tables, and more specialized formatting. The guide also covers choosing the best markdown editors and tools, keyboard shortcuts, and how to integrate markdown into your workflow.
Markdown is a lightweight markup language that uses simple syntax to format plain text documents. It allows writers to add formatting like headers, bold, italics, links, and more without having to write HTML or code. Markdown is popular among technical writers for its simplicity and portability. Learning markdown shortcuts can help writers create documentation faster and more efficiently.
Markdown is a plaintext formatting syntax that converts to HTML. It allows users to write using an easy-to-read and easy-to-write format that can then be converted to structurally valid XHTML (or HTML). Some key benefits of markdown include:
Overall, markdown simplifies formatting while still allowing writers to generate complete HTML documents. The simple markdown syntax allows writers to focus on content instead of code.
Learning markdown shortcuts can benefit technical writers in several ways:
Overall, markdown shortcuts help streamline workflow and boost efficiency for technical writers.
The goal of this guide is to help technical writers learn essential markdown shortcuts. Specifically, writers will learn shortcuts to:
With these markdown shortcuts, technical writers can optimize their workflow to create documentation more efficiently.
The ### symbol in Markdown represents a third-level heading. Headings help structure documents and content by separating sections and establishing hierarchy.
Third-level headings denote subsections under second-level headings. They are useful for:
For example:
Markdown Toolbox## Markdown Formatting
Headings
Text Styling
Lists
Here the third-level headings "Headings", "Text Styling", "Lists" are subsections under the second-level heading "Markdown Formatting".
To create a third-level heading in Markdown, precede the heading text with three hash ### symbols:
### This is a Third-Level Heading
This renders as:
Headings can contain inline formatting like bold and italics. The heading text should be brief and descriptive.
Following these best practices will lead to clean, structured Markdown documents.
Markdown makes adding links incredibly easy with the link syntax. To create a link, enclose the link text in square brackets [], then follow it immediately with the URL in parentheses ().
For example:
[Visit the Markdown Toolbox site](https://www.markdowntoolbox.com)
Renders as:
Visit the Markdown Toolbox site
To speed up inserting links, most Markdown editors provide handy keyboard shortcuts.
Here are some common shortcut keys for inserting Markdown links across popular editors:
Ctrl+K V inserts Markdown linksCtrl+L inserts Markdown link syntaxCtrl + L inserts Markdown links⌘ + L inserts Markdown linksSo if you use VS Code, for example, you can highlight the link text, press Ctrl+K V, then enter the URL to quickly create a properly formatted Markdown link.
These shortcuts eliminate the need to manually type out the Markdown link syntax each time, helping boost productivity for writers working with Markdown documents.
To create a Markdown code block, simply type three backticks ``` followed by a space before your code snippet. After your code, press Return three times to end the formatting and close the code block.
Here is an example Markdown code block:
function helloWorld() {
console.log("Hello World!");
}
Some tips for working with Markdown code blocks:
function helloWorld() {
console.log("Hello World!");
}
--- or asterisks *** are handy Markdown shortcuts to visually separate different topics or categories within your document.Markdown preview allows you to toggle between the editor view and a rendered preview of the Markdown document in Visual Studio Code. This can help streamline the writing process by allowing you to visualize how the formatted Markdown will appear, while still having access to edit the source code.
Here are some useful keyboard shortcuts for Markdown preview in VS Code:
Ctrl + Shift + V - Toggle between editor and preview modesCtrl + K V - Open preview to the side of the editorAdditional shortcuts like refreshing the preview and opening the preview in a new tab are also available. Refer to the Markdown Shortcuts extension for the full set of shortcuts.
With real-time preview and handy keyboard shortcuts, Markdown writing in Visual Studio Code is optimized for efficiency. Technical writers can view formatted documentation as they type, accelerating their workflow.
Markdown is a lightweight markup language that allows you to format text using simple syntax. Here are some of the most common markdown shortcuts technical writers can use to streamline documentation tasks:
# Heading 1## Heading 2### Heading 3**bold text***italicized text*```json { "firstName": "John", "lastName": "Smith", "age": 25 } ```
var example = true[text](https://www.example.com)-, *, or +:>:This is a blockquote
Refer to this Markdown cheat sheet for a quick reference of common syntax. With practice, these text formatting shortcuts can greatly improve efficiency for technical writers working with Markdown documents.
Markdown is a lightweight markup language that allows users to write content using simple syntax that can easily be converted to HTML. There are many popular editors and platforms that support handy Markdown shortcuts to improve efficiency.
Visual Studio Code is a popular code editor with robust Markdown support. Useful shortcuts include:
Ctrl/Cmd + B to toggle bold textCtrl/Cmd + I to toggle italicsCtrl/Cmd + Shift + ] to toggle a block quoteCtrl/Cmd + Shift + V to preview Markdown contentJupyter Notebooks allow creating Markdown documentation alongside executable code cells. Helpful shortcuts include:
Esc + M to toggle between Markdown and code cellsShift + Enter to run a cellJupyter's mix of code and Markdown cells makes it easy to document processes.
GitHub supports Markdown across wikis, issues, pull requests and files, with some additional features like:
Useful shortcuts when editing Markdown files in GitHub repositories include:
Ctrl/Cmd + B for boldCtrl/Cmd + I for italics> to quote text* or - for bullet listsThere are many capable Markdown editors. Considerations when choosing include:
Evaluate based on your individual needs and preferences.
Technical writers can greatly enhance their Markdown documents by utilizing some of the extended syntax and advanced formatting options. These allow creating more complex elements like tables, strikethrough text, emojis, and footnotes.
Tables are invaluable for organizing and presenting data in technical documentation. Markdown offers a simple syntax for creating tables using pipes | and hyphens -.
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Rendered table:
Header 1
Header 2
Header 3
Cell 1
Cell 2
Cell 3
Cell 4
Cell 5
Cell 6
You can align text to the left, right or center within each column by using colons.
Strikethrough text is useful for indicating revisions or marking completed tasks. The syntax is a double tilde ~~ before and after the text.
Task lists help track progress on action items using checkbox syntax. Just add brackets and a space before each task like so:
Emoji and symbols help add visual interest and draw attention to key points. You can add them easily using shortcuts like :smile: or :registered:. Hundreds are supported.
Definition lists allow defining terms inline, great for glossaries or specifying key vocabulary. Use a colon after each term, then indent the definition.
Term 1 : Definition 1
Term 2 : Definition 2
Footnotes make citing sources easy. Just add a caret and brackets around some text[^1] to reference it, then include the footnote text at the bottom.
[^1]: Here is the footnote text.
Using Markdown's extended syntax opens up new formatting possibilities for technical writers to enhance clarity and visual appeal. Options like tables, strikethrough, task lists, emoji, definition lists, and footnotes help communicate complex information more effectively. Mastering these advanced shortcuts can greatly boost document quality and productivity.
Automating workflows is key for efficient markdown management. This section details shortcuts and tools to streamline conversion, splitting documents, and leveraging automation.
Converting markdown to HTML manually can be tedious. Automation scripts streamline this process. Here are some methods:
markdown-it module to parse markdown and output HTML. Run on demand or setup a webhook to trigger on markdown file changes.Automation eliminates repetitive manual conversion steps. Streamline your workflow with scripts for productivity.
Large markdown documents can be hard to manage. Here are some tips:
<!-- split here --> to indicate where to split. Parse these comments out later.Automated splitting makes large docs more manageable. Customize to your workflow needs.
Pandoc is extremely versatile for converting between formats:
Pandoc simplifies working with different formats. Learn more here.
Streamline repetitive markdown tasks with scripts and macros:
Scripting boosts efficiency for high markdown usage. Start simple then expand as needed.
Mac users can take advantage of several handy keyboard shortcuts when working with markdown files in popular editors like Visual Studio Code and Atom.
Some useful shortcuts include:
Command + BCommand + ICommand + Option + 1-6 to designate heading levelsCommand + Option + CCommand + Option + QThese shortcuts can help improve efficiency when writing and formatting markdown documents on a Mac. They reduce the need to manually type markdown syntax or use the mouse for basic formatting tasks.
For Windows users, Visual Studio Code offers robust markdown support through keyboard shortcuts and other features.
Helpful shortcuts include:
Ctrl + Shift + VCtrl + BCtrl + ICtrl + Shift + CAdditional nice-to-have features are autocompletion for markdown syntax, easy access to a cheat sheet, and customizable keyboard bindings.
Together, these capabilities help optimize the markdown authoring workflow for Windows users leveraging Visual Studio Code.
Markdown makes referencing URLs and creating hyperlinks simple through its autolink functionality. When a valid URL or email address is written in markdown, it will automatically convert into a clickable link when rendered.
For example:
https://www.example.com
contact@example.com
Renders as:
https://www.example.com
contact@example.com
This saves the need to manually create links using markdown's link syntax. However, custom links with custom text can still be created manually if more context is needed.
Markdown shortcuts allow writers to format documents more efficiently. Some of the most useful shortcuts covered in this guide include:
# symbol to create different heading sizes, with more # symbols creating smaller headings. For example:# Heading 1
## Heading 2
### Heading 3
** ** for bold or * * for italics. For example:**This text is bold** and *This text is in italics*.
1. First item
2. Second item
- Bullet one
- Bullet two
[Visit Example.com](https://www.example.com)
These shortcuts help streamline formatting to save time and effort.
To integrate markdown seamlessly into your writing workflow:
To continue improving your markdown skills, consider: