Markdown

Markdown is a lightweight markup language. Markdown is easy to read in its raw format, and it can be rendered into HTML, PDF, or other formats. Files are plain text which means they can be edited with many different applications. The initial Markdown specification defined a core set of features, but lacked specifications for useful features like tables. Developers extended Markdown to add helpful features which made Markdown more useful, but created fragmentation in the way Markdown is processed. Therefore, the Markdown created for GitHub may render differently than the same Markdown in a content management system. You can avoid most issues with these different "flavors" of markdown by sticking with a core set of features. This page covers the core of the features I use.

Overall Tips

  • Focus on content, not formatting.
  • Let the tools format the content.
  • Explore linters to keep your syntax neat. In Visual Studio Code, you can use the markdownlint extension.

Title Section

  • At the top of your markdown file, set the title with a single # followed by a space, then the page title.
  • Put an empty line between the section and the content.
# Page Title

Content goes here

There should only be one title in a file.

Paragraphs

  • Create paragraphs simply by typing text on a line.
  • Do not indent paragraphs.
  • Leave a space before and after paragraphs.
## Summary

This is the first paragraph.

This is the second paragraph.

Bold and Italics

Surround text with one star for italics and two stars for bold.

Surround text with one star for *italics* and two stars for **bold**.

Subsections

Use two ## to create level-2 sections. Use ### to create level-3 sections, etc.

## Sub Section

Content here

## Other Sub Section

Other Content Here

### This Section is Nested

Other content here

This page contains tools that I find indispensable for getting work done. Most are open source. All are free or have free versions.

Bulleted Lists

  • Start a line with either a start (*) or dash (-) to create a bullet point.
  • Put a space after the bullet and your content.
## TODO Items

- Thing 3
- Thing 4

## DONE

* Thing 1
* Thing 2
  • I prefer the dash syntax because the star is used for other text formatting.
  • Indent sub-bullets 4 spaces. (Some processors allow 2, but all allow 4, so stick with four.)
- Linux
    - Open source
    - Community driven
- Windows
    - Proprietary
    - Created by Microsoft
  • If you find yourself needing more than 3 levels of bullet points, consider using sections to organize your content.

Numbered Lists

  • You can manually number lists. Just start a line with a number and period.
## Process

1. Do this first
2. This goes second
3. This is last

Use numbered lists sparingly, because if you add an item in the middle of the list, you will have to renumber everything in the list.

Code

  • Many Markdown processors will automatically highlight code syntax.

Inline Code

  • Use backticks to mark code.
Use `chmod u+x` to grant the user execute permissions.

Code Blocks

  • Use three backticks to mark the start and end of the code.
  • Put the name of the language on the first line after the backticks.
```python
for line in lines:
    print(line)
```
  • Surround the clickable part of the link with square brackets, then put the URL in parentheses.
  • To display the bare URL in the page, surround the link with angle brackets (<>).
- [Google](https://www.google.com)
- [Yahoo](https://www.yahoo.com)
- <https://www.bing.com>

Occasionally, the URL might have one or more parentheses. You should encode the parentheses (%28 and %29). For example

[Broke](https://gchq.github.io/CyberChef/#recipe=ROT13(true,true,false,13)&input=aGk)
[Fixed](https://gchq.github.io/CyberChef/#recipe=ROT13%28true,true,false,13%29input=aGk)

You can link to other markdown pages in your directory structure. The links will be relative to the current Markdown file.

- See the [linux](linux.md) page for more information.
- Use [chmod](linux/chmod.md) for permissions info.
- Use [Notepad++](../tools/notepad++) for editing text.

Images

  • You can embed an image in a page with syntax similar to an internal reference, but precede the bracket with an exclamation point.
![Network Overview Diagram](diagram.png)

HTML

  • Markdown lets you mix HTML and Markdown. Use this sparingly.
  • It is sometimes helpful to add the <br tag to force a line break, especially in tables.
# Content

This paragraph<br>will wrap<br>manually.

Obsidian

Settings

  • I prefer to keep images and attachments in sub folders. Find this setting in Options > Files and Links > Default location for new attachments.

Tags

  • Use a hashtag with no space to create a tag. Typically, you want to put tags under the page title.
  • The following example creates 3 tags.
# Linux Permissions

#chmod #linux #acl

Tables

  • Use tables sparingly.
  • The following is a sample table.
Header 1     | Header 2 | Header 3
-------------|----------|---------
One<br>thing | Two      | Three
Four         | Five     | Six
  • The vertical pipe characters do not have to line up perfectly, but it makes it easier to read the raw Markdown.
  • Obsidian lets you use double brackets to create Wiki-style links. This can be helpful when you know you want to create a new page for a topic.
I will put a link to [[AWS Pricing]] here and come back to click that link to create a page.
  • I tend to prefer Wiki-style links in Obsidian, but I use standard Markdown links when creating documentation for publication (like this website).