Markdown Toolbox Logo Markdown Toolbox
Home
Blog

Markdown Shortcuts for Technical Writers

2024-02-16

  • Introduction to Markdown Shortcuts
  • What is ### in Markdown?
  • What is the shortcut for Markdown link?
  • What is the shortcut for the Markdown code block?
  • What is the shortcut for Markdown vs code?
  • Basic Syntax and Markdown Cheat Sheet
  • Markdown Editors & Tools
  • Extended Syntax and Advanced Formatting
  • Markdown Conversion and Automation
  • Markdown Shortcuts for Mac and Windows Users
  • Conclusions and Next Steps

    Markdown Shortcuts for Technical Writers

    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.

    Introduction to Markdown Shortcuts

    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.

    What is Markdown

    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:

    • Lightweight syntax that is readable and easy to write
    • Plain text format allows it to be opened with any text editor
    • Can be converted to HTML/XHTML and used for web pages
    • Portable between platforms and programs
    • Used extensively for technical documentation and writing

    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.

    Benefits of Using Markdown Shortcuts

    Learning markdown shortcuts can benefit technical writers in several ways:

    • Write documentation faster - Shortcuts speed up writing and formatting
    • Improved productivity - Less time spent on styling text means more time creating content
    • Consistent formatting - Shortcuts apply uniform styling for headers, text, lists, etc.
    • Seamlessly convert markdown to HTML - Properly formatted markdown seamlessly converts to HTML with styling intact
    • Collaborate easily - Markdown's simplicity makes it great for collaboration and version control
    • Platform agnostic - Markdown files work across operating systems and devices

    Overall, markdown shortcuts help streamline workflow and boost efficiency for technical writers.

    Goals of This Guide

    The goal of this guide is to help technical writers learn essential markdown shortcuts. Specifically, writers will learn shortcuts to:

    • Properly structure documents with headers, text formatting
    • Create styled lists, tables, links, images
    • Highlight important text snippets
    • Insert code blocks
    • Generate documents faster

    With these markdown shortcuts, technical writers can optimize their workflow to create documentation more efficiently.

    What is ### in Markdown?

    The ### symbol in Markdown represents a third-level heading. Headings help structure documents and content by separating sections and establishing hierarchy.

    Why Use Third-Level Headings

    Third-level headings denote subsections under second-level headings. They are useful for:

    • Organizing long documents into logical parts
    • Highlighting important topics under broader categories
    • Improving scannability for readers

    For example:

    ## Markdown Formatting
    
    

    Headings

    Text Styling

    Lists

    Here the third-level headings "Headings", "Text Styling", "Lists" are subsections under the second-level heading "Markdown Formatting".

    Markdown Syntax

    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:

    This is a Third-Level Heading

    Headings can contain inline formatting like bold and italics. The heading text should be brief and descriptive.

    Usage Tips

    • Only use third-level headings under second-level headings
    • Don't skip heading levels arbitrarily
    • Keep headings short but meaningful

    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:

    • VS Code: Ctrl+K V inserts Markdown links
    • Atom: Ctrl+L inserts Markdown link syntax
    • Typora: Ctrl + L inserts Markdown links
    • MacDown: ⌘ + L inserts Markdown links

    So 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.

    What is the shortcut for the Markdown code block?

    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:

    • You can specify the coding language after the opening backticks to get syntax highlighting. For example:
    function helloWorld() {
      console.log("Hello World!"); 
    }
    
    • Horizontal rules created with three dashes --- or asterisks *** are handy Markdown shortcuts to visually separate different topics or categories within your document.
    • Many popular Markdown editors like Visual Studio Code have handy keyboard shortcuts, code snippets, and autocomplete to help speed up code block creation.
    • Code blocks are very useful for documenting code examples, configuration files, console output, and more as part of software documentation or tutorials.
    • Proper indentation within code blocks is important for readability and preventing formatting issues.

    What is the shortcut for Markdown vs code?

    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 modes
    • Ctrl + K V - Open preview to the side of the editor
    • These shortcuts allow quick access between editing and preview, making it easy to view changes in real-time.

    Additional 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.

    sbb-itb-0cbb98c

    Basic Syntax and Markdown Cheat Sheet

    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, Bold, and Italic

    • Headings can be created by prefixing text with the # symbol. The more # symbols, the smaller the heading size.
    • # Heading 1
    • ## Heading 2
    • ### Heading 3
    • Bold text can be formatted by surrounding words with double asterisks: **bold text**
    • Italic text uses single asterisks: *italicized text*

    Creating and Highlighting Code Blocks

    • Code blocks are created by indenting lines by 4 spaces or fencing lines in triple backticks ```
    • Code can be highlighted by specifying the language after the opening backticks:

    ```json { "firstName": "John", "lastName": "Smith", "age": 25 } ```

    • Inline code uses single backticks: var example = true

    Linking and Embedding Images

    • Links are written like this: [text](https://www.example.com)
    • Images are added using this syntax: ![alt text](image.jpg)

    Ordered and Unordered Lists

    • Unordered lists start lines with -, *, or +:
    • Item 1
    • Item 2
    • Ordered lists use numbers:
    • First item
    • Second item

    Blockquotes and Horizontal Rules

    • Blockquotes are created by prefixing lines with >:

    This is a blockquote

    • Horizontal rules are added with three hyphens, asterisks, or underscores:

    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 Editors & Tools

    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.

    Markdown Shortcuts in Visual Studio Code

    Visual Studio Code is a popular code editor with robust Markdown support. Useful shortcuts include:

    • Ctrl/Cmd + B to toggle bold text
    • Ctrl/Cmd + I to toggle italics
    • Ctrl/Cmd + Shift + ] to toggle a block quote
    • Ctrl/Cmd + Shift + V to preview Markdown content
    • There are also many handy VS Code extensions like Markdown All in One and Markdown Shortcuts to further enhance the editing experience.

    Markdown Shortcuts in Jupyter Notebooks

    Jupyter Notebooks allow creating Markdown documentation alongside executable code cells. Helpful shortcuts include:

    • Esc + M to toggle between Markdown and code cells
    • Shift + Enter to run a cell
    • Tab for code completion and introspection

    Jupyter's mix of code and Markdown cells makes it easy to document processes.

    Quickstart for Writing on GitHub

    GitHub supports Markdown across wikis, issues, pull requests and files, with some additional features like:

    • Task lists
    • Emoji support
    • Automatic link references

    Useful shortcuts when editing Markdown files in GitHub repositories include:

    • Ctrl/Cmd + B for bold
    • Ctrl/Cmd + I for italics
    • > to quote text
    • * or - for bullet lists

    Choosing the Right Markdown Editor

    There are many capable Markdown editors. Considerations when choosing include:

    • Browser extensions like Markdown Here or StackEdit for quick edits
    • Apps like Typora and iA Writer focused purely on reading/writing
    • Note-taking apps with Markdown support like Simplenote and Bear
    • Editors like Visual Studio Code with abundant features

    Evaluate based on your individual needs and preferences.

    Extended Syntax and Advanced Formatting

    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.

    Creating Complex Tables

    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.

    Using Strikethrough and Task Lists

    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:

    • [ ] Incomplete task 1
    • [x] Completed task 2

    Adding Emoji and Special Symbols

    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.

    Defining Terms with Definition Lists

    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

    Citing with Footnotes

    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.

    Markdown Conversion and Automation

    Automating workflows is key for efficient markdown management. This section details shortcuts and tools to streamline conversion, splitting documents, and leveraging automation.

    Automating HTML Conversion

    Converting markdown to HTML manually can be tedious. Automation scripts streamline this process. Here are some methods:

    • Use Pandoc to batch convert markdown files to HTML programmatically. Pandoc has a simple API for conversion automation using scripts.
    • Create a shell script to loop through a folder of markdown files, piping each one to Pandoc to output HTML. Schedule it to run automatically.
    • Build a Node.js script with the markdown-it module to parse markdown and output HTML. Run on demand or setup a webhook to trigger on markdown file changes.
    • Use VS Code Tasks to define and bind a task to quickly convert the open MD file to HTML on save or export.

    Automation eliminates repetitive manual conversion steps. Streamline your workflow with scripts for productivity.

    Splitting and Managing Documents

    Large markdown documents can be hard to manage. Here are some tips:

    • Use multiline comments like <!-- split here --> to indicate where to split. Parse these comments out later.
    • Split on heading levels e.g. level 1 headings using scripts or extensions.
    • Set maximum file sizes or section counts to trigger automated splitting.
    • Use folders by topic to organize files after splitting.
    • Add frontmatter metadata like titles, authors etc to keep things organized.

    Automated splitting makes large docs more manageable. Customize to your workflow needs.

    Leveraging Pandoc for Format Conversion

    Pandoc is extremely versatile for converting between formats:

    • Convert markdown to DOCX, EPUB, LaTeX, Confluence, and more.
    • Leverage Pandoc shortcuts and templates to customize output.
    • Script Pandoc conversion into your workflows with its API.
    • Try Pandoc integrations in VS Code, Jupyter, and other editors.

    Pandoc simplifies working with different formats. Learn more here.

    Scripting and Macros in Markdown

    Streamline repetitive markdown tasks with scripts and macros:

    • Write code snippets to generate markdown tables, links, headers etc programmatically.
    • Create custom markdown syntax as shortcodes to insert reusable content.
    • Use macros in editors like VS Code and Vim to quickly insert markdown elements.
    • Automate report generation from templates using scripts or simple static site generators.

    Scripting boosts efficiency for high markdown usage. Start simple then expand as needed.

    Markdown Shortcuts for Mac and Windows Users

    Keyboard Shortcuts for Markdown on Mac

    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:

    • Bold text - Command + B
    • Italicize text - Command + I
    • Create headings - Command + Option + 1-6 to designate heading levels
    • Insert code block - Command + Option + C
    • Create blockquote - Command + Option + Q

    These 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.

    Visual Studio Code Shortcuts on Windows

    For Windows users, Visual Studio Code offers robust markdown support through keyboard shortcuts and other features.

    Helpful shortcuts include:

    • Preview markdown - Ctrl + Shift + V
    • Bold text - Ctrl + B
    • Italic text - Ctrl + I
    • Insert code block - Ctrl + Shift + C

    Additional 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.

    Autolinked References and URLs

    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.

    Conclusions and Next Steps

    Summary of Key Markdown Shortcuts

    Markdown shortcuts allow writers to format documents more efficiently. Some of the most useful shortcuts covered in this guide include:

    • Headings - Use the # symbol to create different heading sizes, with more # symbols creating smaller headings. For example:
    # Heading 1 
    ## Heading 2
    ### Heading 3
    
    • Bold/Italics - Surround text with either ** ** for bold or * * for italics. For example:

    **This text is bold** and *This text is in italics*.

    • Lists - Create numbered or bulleted lists by preceding list items with either numbers and periods or asterisks. For example:
    1. First item 
    2. Second item
    
    
    • Bullet one
    • Bullet two
    • Links - Format links by surrounding the desired linked text in square brackets followed by the URL in parentheses. For example:

    [Visit Example.com](https://www.example.com)

    These shortcuts help streamline formatting to save time and effort.

    Integrating Markdown into Your Workflow

    To integrate markdown seamlessly into your writing workflow:

    • Use a markdown editor like Visual Studio Code for drafting and formatting documents. Their preview features allow you to view formatted text side-by-side with markdown syntax.
    • Employ snippets and keyboard shortcuts in your editor for quick access to common markdown elements like links or lists.
    • Use markdown for internal documentation to streamline formatting and allow non-technical colleagues to access source files directly.
    • Store your markdown files in cloud sync services like Dropbox to enable multi-device access and real-time cloud backup.
    • Export finalized markdown documents to HTML or PDF formats for broader sharing and publishing.

    Expanding Your Markdown Skills

    To continue improving your markdown skills, consider:

    • Completing online courses on platforms like Udemy or LinkedIn Learning to level up your expertise with markdown shortcuts and advanced formatting techniques.
    • Reading markdown tutorials on sites like Markdown Guide for expanded details on markdown syntax and best practices.
    • Joining markdown-focused communities on Reddit or Stack Overflow to exchange tips with other users.
    • Experimenting hands-on with new markdown features on a test document to gain practical experience.
    • Enabling linter plugins in your editor to surface errors for a chance to refine your markdown abilities.