Get Started with Markdown Important Note Basics

To get started with Markdown, you'll want to understand the basics. Markdown is a lightweight markup language that allows you to create formatted text using plain text syntax.

The most basic Markdown elements are headers, which are denoted by one or more # symbols. For example, a single # symbol creates a first-level header, while multiple # symbols create subsequent levels.

Headers are essential for organizing your content, and they're easy to create. Simply type a # symbol followed by a space and your header text, and you're done.

Markdown formatting is straightforward and easy to learn. It uses simple syntax to create headings, bold and italic text, and other visual elements.

To create a heading in markdown, you surround the text with one or more # symbols, with the number of symbols indicating the heading level. For example, a single # symbol creates a top-level heading, while multiple symbols create subheadings.

You can also use markdown to create bold and italic text by surrounding the text with double asterisks (**) for bold and single asterisks (*) for italic. For instance, this text will be bold, and *this text will be italic*.

Anchor links are a useful feature in Markdown files, allowing you to create links to specific sections within a file or even another Markdown file.

Punctuation marks and leading white spaces within a file name are ignored when creating anchor links.

Upper case letters are converted to lower case letters, making it easier to create consistent IDs for your headings.

Spaces between letters are replaced with dashes (-), which is how the ID is generated.

Here's a quick rundown of the conventions for anchor links:

By following these conventions, you can easily create anchor links to specific sections within your Markdown files.

In Git tools, hitting enter between two lines of text will join them into a single paragraph, which is called wrapping text.

You can create separate paragraphs by leaving a blank line between them.

GitLab's web interface and many desktop Git tools already feature substring change highlighting within lines, so artificial line breaks are not necessary.

Markdown doesn't natively support underlined text, but you can use the HTML tag ins to create it if needed.

Hardcoding underlined text with the ins tag is not recommended.

Special characters can be tricky to insert in Markdown, but don't worry, I've got you covered.

To insert a backslash, you simply prefix it with another backslash, like this: \. This is super helpful if you need to include a backslash in your text.

The same goes for other special characters, like the underscore, which is inserted by prefixing it with a backslash: _. I've found this to be really useful when writing code snippets.

Curly braces, square brackets, and parentheses can also be inserted by prefixing them with a backslash: {}, [], and (), respectively. This is a lifesaver when trying to include complex syntax in your Markdown text.

If you need to include a hash mark, plus sign, minus sign, period, exclamation mark, or asterisk, simply prefix it with a backslash: #, +, -, ., !, and *, respectively. I've used this technique to highlight important notes in my own Markdown documents.

To include mathematical notation, surround it with a dollar sign for inline notation or double dollar signs for block notation. For example, $2+2$ or $$x^2 + y^2 = z^2$$. This is a great way to add some math to your Markdown text without getting bogged down in complicated syntax.

Code and Comments are essential elements in Markdown, and understanding how to use them effectively can make a big difference in how your content is presented.

To highlight code segments, wrap the code with three backtick quotes on a new line at both the start and end of the block, like this: ```. To indicate code inline, use one backtick quote, as in `.

You can also use four spaces at the beginning of a line to automatically convert the text to a code block. This is a simple and convenient way to add code snippets to your Markdown files.

Code Blocks are a great way to display code in a Markdown file. You can use backticks to indicate a span of code.

To indicate a code block, wrap your code with three backtick quotes on a new line at both the start and end of the block. This is the same way to indicate a code block as in the command to install the Microsoft Cross Platform Build & Release Agent: `$ sudo npm install vsoagent-installer -g`.

You can also use four spaces at the beginning of a line to automatically convert the text to a code block. This is a handy feature to know about.

Links are a crucial part of code and comments, allowing you to reference specific work items, pages, and documents with ease. You can automatically format HTTP and HTTPS URLs as links in pull request comments and wikis by simply entering the URL.

In Markdown files and widgets, you can create text hyperlinks using the standard Markdown link syntax. For example, to link to another Markdown page in the same repository, you can use a relative path like this: [text to display](target.md).

You can also use absolute paths in Git or TFVC repositories, like this: [text to display](/folder/target.md) for Git or [text to display]($/project/folder/target.md) for TFVC.

Here are some examples of supported links:

Note that links to documents on file shares using file:// aren't supported for security purposes.

The Handbook is a great resource for learning about markdown, a lightweight markup language that's easy to write and use. It's used by web developers and is a great tool to have in your toolkit.

The Handbook was generated by Hugo, a blog-aware Static Site Generator (SSG) that's widely used by web developers. Hugo uses a markdown engine, which is a system to write documents that makes them syntactically distinguishable from text.

We use Goldmark, an advanced Markdown engine written in Go, which comes bundled as part of Hugo. Goldmark implements the CommonMark markdown standard and is fast at transforming Markdown to HTML.

If you're new to markdown, don't worry, it's easy to learn and even easier to use. You'll probably be surprised how handy it is once you get used to it.

There are two types of comments that can be used in a repository. The first type allows you to leave comments in a markdown file which can only be viewed in the repository.

These comments are not rendered to HTML or included in a page's source. They're essentially hidden from public view.

The second type is a standard HTML comment which will be included in the pages source. This means anyone viewing the page will see the comment.

Diagrams can be a great way to visualize complex ideas in your code and comments.

There are two popular ways to insert diagrams with Markdown: Mermaid and PlantUML.

These tools allow you to create diagrams directly in your code, which can be very convenient.

Here are the two options in more detail:

Both Mermaid and PlantUML can help make your code and comments more readable and understandable.

The markdown important note feature offers several advanced features that make it stand out. It supports multiple levels of headings, allowing you to structure your content in a clear and concise manner.

You can create headings from H1 to H6, making it easy to organize your notes and prioritize important information. This is particularly useful when you need to highlight key points or summarize complex ideas.

The feature also allows you to use strikethrough text, which is helpful when you want to indicate that a particular point has been resolved or corrected.

Joplin supports a number of plugins that can be toggled on/off to enable/disable markdown features.

These plugins are not part of the CommonMark spec, so while they will work within Joplin, it's not guaranteed they will work in other Markdown readers.

You can enable or disable these plugins in the markdown section of the Configuration screen.

Some plugins, like Soft breaks and Typographer, are not enabled by default.

Linkify is enabled by default and auto-detects URLs to convert them into clickable links.

Other plugins, like Mermaid and Footnote, are also enabled by default and offer advanced features like diagram rendering and inline footnotes.

Here's a list of some of the available plugins:

These plugins can be used to add advanced features to your markdown documents, but keep in mind that they may not work in other Markdown readers.

Markdown editors can be a huge help if you're not used to writing markdown. Many editors offer real-time previews that give you a good idea of what the output will be while you type.

Mac users have several options, including MacDown, iA Writer, and Ulysses. These editors allow you to type and preview simultaneously, making it easier to see how your markdown will look.

In-browser markdown editors like StackEdit are also available. This option is great because it works from every major browser and automatically saves your work to Google Drive.

If you're away from your computer or out of resources, StackEdit is a great way to work on a markdown file. It's accessible from any browser, making it a convenient option.

For a quick and easy way to copy a hyperlink title and address in markdown, consider using the Format Link extension. This extension also allows you to customize other formats.

Here are some markdown editors you can use:

These editors can help you create and edit markdown files with ease.

Tables are a great way to present data in a clear and organized manner. You can use them to compare different values or show relationships between them.

A table can be created using the syntax `| column 1 | column 2 | column 3 |`, and each row is separated by a new line. This is a simple and effective way to present data.

For example, a table with three columns and two rows might look like this: `| Column 1 | Column 2 | Column 3 |` followed by `| Value 1 | Value 2 | Value 3 |` and `| Value 4 | Value 5 | Value 6 |`.

You can also use Markdown to add headers to your table, making it easier to read and understand.