Markdown Syntax Guide
In PinotWalk, articles are edited using Markdown syntax. PinotWalk's policy is not to cover all HTML syntax in order to maintain consistency in expression. However, we do aim to cover basic Markdown syntax.
Introduction
Markdown is a lightweight markup language created by John Gruber in 2004. It allows you to create documents using plain text and convert them to HTML.
Benefits of Markdown
- Easy to read and write
- Simple syntax
- Supported by many platforms
- Can be edited with any text editor
Headings
There are 6 levels of headings:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Alternative syntax:
Heading 1
=========
Heading 2
---------
Heading 1
Heading 2
Important Points:
- Add blank lines before and after headings
- Add a space after
# - Use headings with hierarchical structure in mind
Paragraphs and Text Formatting
Paragraphs
Paragraphs are separated by blank lines.
This is the first paragraph.
This is the second paragraph.
This is the first paragraph.
This is the second paragraph.
Line Breaks
For text, line breaks are reflected using a newline or <br>. Use <br> to insert a line break between sentences.
Text Formatting
**bold**
__bold__
*italic* *italic*
_italic_ _italic_
***bold and italic***
___bold and italic___
~~strikethrough~~
`inline code`
Superscript: X<sup>2</sup>
Subscript: H<sub>2</sub>O
Actual display:
bold
italic italic
italic italic
bold and italic
strikethrough
inline code:
- Superscript: X2
- Subscript: H2O
Highlight
==highlight==
==highlight==
Text Color
In PinotWalk, you can use the HTML <span> tag within Markdown.
It is recommended to specify colors using PinotWalk's predefined <span class="text-XXX"> classes.
This is normal text.
<span class="text-red">This is red text.</span>
<span class="text-bourgogne">This is PinotWalk's brand color.</span>
<span style="color: red;">Red text using style</span>
This is normal text.
This is red text.
This is PinotWalk's brand color.
Red text using style
Available Colors
Standard Colors
- text-red - Red (warning, error)
- text-blue - Blue (information, link)
- text-green - Green (success, positive)
- text-orange - Orange (caution)
- text-purple - Purple (special notes)
- text-gray - Gray (subdued text)
PinotWalk Brand Colors
- text-bourgogne - Bright pink-red
- text-bordeaux - Deep wine red
- text-pinot - Deep brown-red
✅ Other Allowed Syntax
<span style="color: red;">Red text</span>
<span style="color: #ff0000;">Red text</span>
<span style="color: rgb(255, 0, 0);">Red text</span>
<span style="color: hsl(0, 100%, 50%);">Red text</span>
Red text
Red text
Red text
Red text
Lists
Bullet Lists
- Item 1
- Item 2
- Sub-item 1
- Sub-item 2
- Sub-sub-item
- Item 3
* Item a
* Item b
+ Item A
+ Item B
- Item 1
- Item 2
- Sub-item 1
- Sub-item 2
- Sub-sub-item
- Item 3
- Item a
- Item b
- Item A
- Item B
Numbered Lists
1. First item
2. Second item
1. Sub-item 1
2. Sub-item 2
3. Third item
- First item
- Second item
- Sub-item 1
- Sub-item 2
- Third item
Checklists
- [x] Completed task
- [ ] Incomplete task
- [x] Sub-task 1
- [ ] Sub-task 2
- [x] Completed task
- [ ] Incomplete task
- [x] Sub-task 1
- [ ] Sub-task 2
Links and Images
Links
[Display text](https://pinotwalk.com/)
[1]: https://pinotwalk.com
[reference]: https://pinotwalk.com "PinotWalk"
Display text
Reference link
Named reference link
Inserting Images
In PinotWalk, to insert an image, select it using the Choose File button at the bottom of the editing screen, then click the upload image button. The image will be inserted at the cursor position in the editing box. The filename is set to be unique for each account. (If you use the same filename in a different blog, it will conflict and display the image from the first upload.)
Blockquotes
Basic Blockquotes
> This is a blockquote.
> You can quote across multiple lines.
> Line breaks are preserved.
>
>
>
> Multiple line breaks are sanitized.
This is a blockquote.
You can quote across multiple lines.
Line breaks are preserved.Multiple line breaks are sanitized.
Nested Blockquotes
> Outer quote
>> Inner quote
>>> Even deeper quote
Outer quote
Inner quote
Even deeper quote
Using Other Elements in Blockquotes
> ### Heading in a blockquote
>
> - List item 1
> - List item 2
>
> You can use **bold** and *italic* too.
Heading in a blockquote
- List item 1
- List item 2
You can use bold and italic too.
Writing Code
Inline Code
Use backticks to include `code` in text.
Use backticks to include code in text.
Code Blocks
```言語名
コードブロック
複数行に渡って記述可能
```
Supported Language Examples:
-
python
```python def hello(): print("Hello, World!") ``` -
javascript
```javascript function hello() { console.log("Hello, World!"); } ``` -
css
```css body { background-color: #f0f0f0; } ```
Syntax Highlighting
Many Markdown processors support the following languages:
- HTML, CSS, JavaScript
- Python, Ruby, PHP
- Java, C++, C#
- And many more
Tables
Basic Tables
| col1 | col | col3 |
|-----|-----|-----|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
| col1 | col | col3 |
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
Cell Alignment
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
| Left-aligned | Center-aligned | Right-aligned |
|---|---|---|
| A1 | B1 | C1 |
| A2 | B2 | C2 |
Complex Tables
| Item | Description | Notes |
|------|-------------|-------|
| Item1 | Description spanning<br>multiple lines | Note1 |
| Item2 | You can use *italic* and **bold** | Note2 |
| Item3 | `code` and [links](URL) are also possible | Note3 |
| Item | Description | Notes |
|---|---|---|
| Item1 | Description spanning multiple lines |
Note1 |
| Item2 | You can use italic and bold | Note2 |
| Item3 | code and links are also possible |
Note3 |
Other Elements
Horizontal Rules
Use any of the following (3 or more characters):
---
***
___
Comments
<!-- This is a comment. It will not be displayed -->
⇒ Not displayed
Footnotes
You can add footnotes[^1] in the text.
You can add another footnote[^2] in the text.
[^1]: This is the content of footnote 1.
[^2]: This is the content of footnote 2.
You can add footnotes[^1] in the text. Footnote 1 will be displayed at the end.
You can add another footnote[^2] in the text. Footnote 2 will be displayed at the end.
[^1]: This is the content of footnote 1.
[^2]: This is the content of footnote 2.
Automatic Table of Contents
PinotWalk automatically generates a table of contents based on the structure written in Markdown.
Extended Markdown Syntax
Math Equations: LaTeX (MathJax) Notation
Inline equation: $E = mc^2$
Block equation:
$$
\frac{d}{dx}e^x = e^x
$$
$$
|\psi_+|^2 =N^2 (|\phi_1|^2 +|\phi_2|^2 + 2\Re(\phi_1^*\phi_2))
$$
Inline equation: $E = mc^2$
Block equation:
$$
\frac{d}{dx}e^x = e^x
$$
$$
|\psi_+|^2 = N^2 (|\phi_1|^2 +|\phi_2|^2 + 2\Re(\phi_1^* \phi_2))
$$
$$
\begin{pmatrix}
0 & 1 \\
1 & 0
\end{pmatrix}
$$
$$
\begin{pmatrix}
0 & 1 \
1 & 0
\end{pmatrix}
$$
- Other Restrictions
-
Brackets
\left{and\right}are not supported. Please use regular{}instead.$ \left{ abc \right} $$ \left{ abc \right} $
-
Subscripts and Line Breaks
The LaTeX subscript symbol_may conflict with the Markdown italic symbol_, causing display issues. You can resolve this by adding spaces or line breaks.$$ \phi^{abc}_{efg} $$ #No line break here $$ \hat{\sigma_x}_{xyz} $$ TThis is $\phi^{abc}_{efg}$, $\hat{\sigma_x}_{xyz}$ that is $\hat{\sigma_x}_{xyz}$.[Display Issue Example]
$$
\phi^{abc}{efg}
$$
$$
\hat{\sigma}{xyz}
$$This is $\phi^{abc}{efg}$, $\hat{\sigma_x}{xyz}$ that is $\hat{\sigma_x}_{xyz}$.
$$ \phi^{abc}_{efg} $$ #Line break here $$ \hat{\sigma_x}_{xyz} $$ This is $\phi^{abc}_{efg}$, $\hat{\sigma_x}_{xyz}$ that is $\hat{\sigma_x}_{xyz}$.[Improved Example]
$$
\phi^{abc}_{efg}
$$$$
\hat{\sigma_x}_{xyz}
$$This is $\phi_{efg}^{abc}$, that is $\hat{\sigma_x}_{xyz}$.
-
Collapsible Sections
<details>
<summary>Click to expand</summary>
> Write detailed content here.
> Line breaks are also possible.
</details>
Click to expand
Write detailed content here.
Line breaks are also possible.
Keyboard Keys
<kbd>Ctrl</kbd> + <kbd>C</kbd>
Ctrl + C
Best Practices
-
Maintain Consistency
- Use the same heading level for similar types of headings
- Unify list markers
- Align indentation
-
Prioritize Readability
- Add appropriate blank lines
- Organize long documents with headings
- Use tables only when necessary
-
Maintainability
- Avoid complex structures
- Use comments appropriately
- Keep images and links in manageable formats
-
Accessibility
- Set appropriate alt text for images
- Convey information through shapes, not just colors
- Structure content considering screen readers
Troubleshooting
Common Issues and Solutions
-
Lists not displaying correctly
- Check if there are blank lines before and after the list
- Verify correct indentation
- For mixed lists, check the hierarchy
-
Line breaks not working
- Try adding two spaces at the end of the line
- Use
<br>tag if needed - Add a line break before the
<br>tag
-
URL/Image not displaying
- Verify the URL is correct
- Check if the image file exists
- Try uploading again
-
Table is broken
- Check if the number of columns matches in each row
- Verify each column has at least 3
-in the separator line - Check if
|positions are aligned
Tips
Editor Preview Function
Real-time preview is displayed on the right side of the editing screen.
You can write while checking if the syntax is correct.
Learn Common Syntax First
Initially, learning headings, lists, links, and code blocks is sufficient.
References
For more detailed Markdown syntax, please see the following tutorials.
Summary
Markdown is a very flexible and powerful syntax. Once you learn the basics, you can quickly create practical documents. By using advanced features as needed, you can create more expressive documents.
We recommend practicing by actually creating documents while referring to this guide. The more you use it, the more you'll appreciate Markdown's convenience.
Comments