New MD-formatting !publish!
This commit is contained in:
parent
a2e5fa90a5
commit
22238eb423
1 changed files with 456 additions and 0 deletions
456
content/article/md-formatting.md
Normal file
456
content/article/md-formatting.md
Normal file
|
|
@ -0,0 +1,456 @@
|
|||
---
|
||||
title: "Markdown formatting guide"
|
||||
date: "2023-06-28T01:58:32+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
draft: false
|
||||
keywords:
|
||||
- markdown guide
|
||||
- guide
|
||||
abstract: |
|
||||
This is a Markdown formatting guide.
|
||||
publishDate: "2021-06-28T01:58:32+03:00"
|
||||
---
|
||||
|
||||
[Pandoc]: https://pandoc.org/ "universal document converter."
|
||||
|
||||
# What is Markdown
|
||||
|
||||
Markdown is an open standard for a flexible, human-readable, lightweight mark-up language for formatting text. It was developed by John Gruber and the late Aaron Swartz, and released in 2004. Markdown files have the extension ‘*.md*’ and consist of plain text, therefore they can be opened, edited and read using any text editor, rudimentary or otherwise.
|
||||
|
||||
Since its release in 2004 Markdown has been adopted widely for multiple applications -- for example by *GitHub* (for repository readme files), by R (as R Markdown), for note-taking and collaborative writing applications (e.g. *Obsidian*, *hackmd.io*, *Zotero*, *Nextcloud*), for chat applications (e.g. *Element*), and also by static website frameworks (e.g. *Hugo* and *Jekyll*).
|
||||
|
||||
Although one can read and write Markdown using a basic notepad, it is recommended to use a text editor with Markdown support such as [Obsidian](https://obsidian.md/), or [Visual Studio Code](https://code.visualstudio.com/.). For an online Markdown editor see [hackmd.io](https://hackmd.io/).
|
||||
|
||||
Markdown documents can be converted to multiple other document formats. Tools like [Pandoc][] allow working with and compiling bibliographic references, and can render Markdown files into pdf, docx, txt, html, epub, and many other file formats (see ).
|
||||
|
||||
# Markdown formatting guide
|
||||
|
||||
The following demonstrates how to write in Markdown and shows how Markdown is rendered by this website.
|
||||
For external resources on Markdown see the [Notes section](#notes).
|
||||
|
||||
## Writing in Markdown [draft]
|
||||
Markdown is a plain text format, intended for digital text. Unlike conventional word processors that go by the
|
||||
|
||||
that simulate writing on paper and follow the what-you-see-is-what-you-get (WYSIWYG) concept.
|
||||
|
||||
Markdown is intended to facilitate writing and reading.
|
||||
|
||||
em dash -- with some content inside -- is useful.
|
||||
|
||||
*Formatting:*
|
||||
```
|
||||
This will
|
||||
appear as
|
||||
a single
|
||||
line.
|
||||
```
|
||||
|
||||
*Appearance:*
|
||||
This will
|
||||
appear as
|
||||
a single
|
||||
line.
|
||||
|
||||
## Text formatting
|
||||
|
||||
| Formatting | Appearance|
|
||||
|-|-|
|
||||
|`normal text`| normal text|
|
||||
| `*emphasis*`| *emphasis*|
|
||||
| `**bold**`| **bold**|
|
||||
| `***bold emphasis***`| ***bold emphasis***|
|
||||
| `~~strikethrough~~`| ~~strikethrough~~|
|
||||
| \`code blocks\`| `code blocks`|
|
||||
| `something<sup>superscript</sup>` | something<sup>superscript</sup>|
|
||||
| `something<sub>subscript</sub>` | something<sub>subscript</sub> |
|
||||
| `\* \~ \[ \{ \#` | \* \~ \[ \{ \#|
|
||||
|
||||
## Headings and subheadings {#headings}
|
||||
|
||||
Headings make use of the hashtag character, as follows:
|
||||
|
||||
```
|
||||
# Heading
|
||||
## Sub-heading
|
||||
### Sub-sub-heading
|
||||
```
|
||||
*Note that a space is required between the hashtag character and the header text. For creating links to specific headings of the same document see [internal links](#internal-links)*
|
||||
## Lists
|
||||
|
||||
Markdown bullet lists use the dash/minus symbol as in:
|
||||
```
|
||||
- bullet 1
|
||||
- bullet 2
|
||||
- sub-bullet 2.1
|
||||
```
|
||||
|
||||
Numbered lists start with a number followed by a period as in:
|
||||
```
|
||||
1. List item 1,
|
||||
2. List item 2,
|
||||
1. Sub-item 2.1
|
||||
```
|
||||
|
||||
Bullet list appearance:
|
||||
- bullet 1
|
||||
- bullet 2
|
||||
- sub-bullet 2.1
|
||||
|
||||
Numbered list appearance:
|
||||
1. List item 1,
|
||||
2. List item 2,
|
||||
1. Sub-item 2.1
|
||||
|
||||
*Note that both cases require a space before the list item text.
|
||||
To add depth, add two spaces or a tab in a subsequent list item.
|
||||
Lists should not have empty lines between items.*
|
||||
|
||||
## Quotes [draft]
|
||||
|
||||
*Blockquotes:*
|
||||
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
|
||||
|
||||
*Blockquote formatting:*
|
||||
|
||||
```
|
||||
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
|
||||
```
|
||||
|
||||
*Inline quotes:*
|
||||
For shorter quotes, use inline quotes, between "quotation marks" and should be followed by a reference (Author 2015).
|
||||
|
||||
Note that:
|
||||
- > If *you emphasized some text yourself you need to mention that in the reference* (Author et al. 2010; emphasis mine).
|
||||
- > Or if your quote includes an *emphasis found in the original* (Author et al. 2020, emphasis in original).
|
||||
- If your inline quote includes a world
|
||||
|
||||
- [how to mention 'et al.' : Author and colleagues or Author et al.?]
|
||||
- [example of normal in-line quote]
|
||||
- [omitting author from ref] Discussing x, Author described that "this is a good case of" (2010).
|
||||
- [example of quote edit]
|
||||
- [example of transcript]
|
||||
- [example of emphasis]
|
||||
|
||||
## Images
|
||||
|
||||
Recommended and supported image formats are:
|
||||
- PNG for rasterized content.
|
||||
- SVG for vector content.
|
||||
|
||||
Avoid image formats that are lossy and can introduce artifacts (e.g. JPG).
|
||||
|
||||
*Image formatting pseudocode*:
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
The examples below use the same graphic put together in Illustrator and exported to:
|
||||
- SVG (file size: 3KB; export optimized for text; selectable text)
|
||||
- PNG (file size: 56KB; export resolution x3 @ 2100x900; transparent background)
|
||||
|
||||
*Image formatting example*:
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*Note: to view the full resolution version of an image, right click on an image and select "Open image in new tab".*
|
||||
|
||||
## Tables
|
||||
|
||||
*Table formatting*:
|
||||
```
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|--|--|--|
|
||||
| This | is | a|
|
||||
| table | with | content.|
|
||||
```
|
||||
|
||||
*Table appearance*:
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|--|--|--|
|
||||
| This | is | a|
|
||||
| table | with | content.|
|
||||
|
||||
|
||||
*Note: The number of dashes in the second row, as well as the white space inside individual cells are arbitrary, and can modified to make the table more easily readable while writing/editing.*
|
||||
|
||||
|
||||
### Table column alignment
|
||||
|
||||
In case alignment is important, it can be assigned per column.
|
||||
|
||||
*Formatting*:
|
||||
```
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|:--|:--:|--:|
|
||||
| left | center | right|
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|:--|:--:|--:|
|
||||
| left | center | right|
|
||||
|
||||
### Headerless tables
|
||||
|
||||
For a table without headers, leave the initial row empty.
|
||||
|
||||
*Formatting*:
|
||||
|
||||
```
|
||||
| | |
|
||||
|-|-|
|
||||
|A|table|
|
||||
|without|headers|
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
| | |
|
||||
|-|-|
|
||||
|A|table|
|
||||
|without|headers|
|
||||
|
||||
## Bibliography
|
||||
|
||||
To incorporate bibliographic referencing (citations and references) in Markdown documents see the  guide.
|
||||
|
||||
## Links
|
||||
|
||||
### Hyperlinks
|
||||
|
||||
*Hyperlink formatting*:
|
||||
|
||||
```
|
||||
[hyperlink caption](https://hyperlink-destination.org)
|
||||
```
|
||||
|
||||
*Hyperlink appearance*: [hyperlink caption](https://hyperlink-destination.org).
|
||||
|
||||
*Note: Do not omit the `http://` or `https://` part of the URL.*
|
||||
|
||||
### Internal links to sections of the document {#internal-links}
|
||||
|
||||
Links to headings or subheadings of the same document use a syntax similar to hyperlinks. There are two ways to create such links. The recommended way is to assign a custom id to a heading, and use that custom id as a the destination of the link:
|
||||
1. To assign an id to a heading, follow the example below (where `myheading-id` is a placeholder):
|
||||
```
|
||||
## This is a Subsection {#myheading-id}
|
||||
```
|
||||
2. To create a link to that section use the syntax:
|
||||
```
|
||||
[go to my subsection](#myheading-id)
|
||||
```
|
||||
|
||||
For example, the section "Headings and subheadings" above, has the id `headings`:
|
||||
```
|
||||
## Headings and subheadings {#headings}
|
||||
```
|
||||
To link to that heading via id follow the syntax: `[go to Headings section](#headings)`, which appears as [go to Headings section](#headings).
|
||||
|
||||
---
|
||||
The second, suboptimal and more laborious way to create document-internal links is to convert a heading title to a destination. Example:
|
||||
- To link to the heading:
|
||||
```
|
||||
### My Heading Title
|
||||
```
|
||||
- Follow the syntax:
|
||||
```
|
||||
[Link caption](#my-heading-title)
|
||||
```
|
||||
|
||||
As follows, to link to the first section of this entry with heading, as in:
|
||||
`# What is Markdown` would be: `[go to 'What is Markdown'](#what-is-markdown)`, which will appear as: [go to 'What is Markdown'](#what-is-markdown).
|
||||
|
||||
*Note that linking to headings via custom ids is much more reliable, since heading titles can change anytime, thus causing a link-by-title to break. Furthermore, heading titles can be quite long which is impractical and can also result in mistyped link destinations. Note also that broken links are not detected: e.g. [this is an internal link to an inexistent heading](#some-heading-that-doesnt-exist).*
|
||||
|
||||
### Footnotes
|
||||
|
||||
The syntax for inserting a footnote is `[^key]`, where `key` can be arbitrary. The content of the footnote can be placed anywhere in the document, and follows the syntax `[^key]: Footnote content.`
|
||||
|
||||
Here is a sentence with a footnote.[^fn] Footnotes are placed *after* a period or comma, like here.[^fn] Footnotes can be reused, and Sandpoints will generate dynamic backlinks to all mentions of the same footnote.[^fn]
|
||||
|
||||
[^fn]: This is the text of a footnote, used 3 times.
|
||||
|
||||
Formatting:
|
||||
|
||||
```
|
||||
Here is a sentence with a footnote.[^fn]
|
||||
[^fn]: This is the text of a footnote, used 3 times.
|
||||
```
|
||||
|
||||
## Links within this project
|
||||
|
||||
*Note: these require a fork or a clone of this site.*
|
||||
|
||||
### Links to other entries of this site
|
||||
|
||||
|
||||
|
||||
The convention for links to other entries of this project is:
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
Examples:
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
Appearance:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Links to Library items
|
||||
|
||||
[Library]: /library/BROWSE_LIBRARY.html "Project library."
|
||||
|
||||
Library items can be referenced inside entries of this website.
|
||||
To reference a library item inside a Markdown entry of this project do:
|
||||
|
||||
```
|
||||
.
|
||||
```
|
||||
|
||||
Where `the-book-id` is a placeholder for the unique id of a library item (in the style of `625e5562-38bc-4497-adaa-5142ef810c4a`). To get the id of an item, go to the [Library][], find the item you want to reference, and copy the last part of it’s URL after `.../book/`.
|
||||
|
||||
Example library reference:
|
||||
```
|
||||
|
||||
```
|
||||
Appearance:
|
||||
|
||||
|
||||
|
||||
*Note: the formatting convention `` will automatically generate a bibliographic citation (as in the example above). To use a custom text associated with a library reference add some text in the square brackets of the link as in ``.*
|
||||
|
||||
## Code blocks
|
||||
|
||||
Code blocks are segments that ignore Markdown formatting, and will be compiled verbatim.
|
||||
For inline code blocks enclose text within backticks, as in:
|
||||
|
||||
```
|
||||
'inline code block'
|
||||
```
|
||||
that will appear as:
|
||||
`inline code block`
|
||||
|
||||
For multiline code blocks enclose text between two sets of triple backticks (<code> ```</code> ).
|
||||
```
|
||||
code blocks will ignore markdown formatting, e.g.
|
||||
![]() ## ** {{}} [^footnote]
|
||||
|
||||
```
|
||||
|
||||
|
||||
## Embedded content [THIS WE NEED TO TALK ABOUT]
|
||||
|
||||
Hugo can embed a range of different media via shortcodes (see [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/)). Note that embedded media cannot be exported to PDF or printed.
|
||||
|
||||
*More importantly, embedded content could disappear any time. To properly archive media it is recommended to add such items to the [Library][], and refer to them via a link -- this can be facilitated by editors.*
|
||||
|
||||
---
|
||||
|
||||
YouTube, and Vimeo videos can be easily embedded using video ids (the last bit of their URLs). Examples:
|
||||
|
||||
{{< youtube UEoDJ1v6U6U >}}
|
||||
<figcaption>Video 1: Video caption.</figcaption>
|
||||
|
||||
{{< vimeo 55073825 >}}
|
||||
<figcaption>Video 2: Video caption.</figcaption>
|
||||
|
||||
Formatting (*note: remove \* characters*):
|
||||
```
|
||||
{{*< youtube UEoDJ1v6U6U >*}}
|
||||
<figcaption>Video 1: Video caption.</figcaption>
|
||||
|
||||
{{*< vimeo 55073825 >*}}
|
||||
<figcaption>Video 2: Video caption.</figcaption>
|
||||
```
|
||||
|
||||
### GitHub Gists
|
||||
|
||||
Example:
|
||||
{{< gist cmiltiadis 0c458dcea8b8569398f5988b0151636c >}}
|
||||
<figcaption>Codegist 1: Gist caption.</figcaption>
|
||||
|
||||
Formatting (*note: remove \* characters*):
|
||||
```
|
||||
{{*< gist username gistId >*}}
|
||||
<figcaption>Codegist 1: Gist caption.</figcaption>
|
||||
```
|
||||
|
||||
### Videogame embedding [DRAFT]
|
||||
|
||||
Implement Unity WebGL embed described here:
|
||||
https://michaelcassidy.net/post/hugo-shortcode-for-embedding-unity-webgl-players-updated-with-code/
|
||||
|
||||
This should allow embedding games as follows (note: square brackets need to be replaced with curly brackets):
|
||||
```
|
||||
> [[< unity-webgl-player game
|
||||
> Title="My cool game"
|
||||
> width="1024" height="576"
|
||||
> buildURL="https://somewhere.com/path/to/files/Build"
|
||||
> buildFileName="webgl"
|
||||
> playerID="" >]]
|
||||
```
|
||||
|
||||
## Other Markdown formatting conventions
|
||||
|
||||
The following includes formatting that might be useful while writing, but has limited application in published material.
|
||||
|
||||
### Horizontal dash
|
||||
|
||||
Formatting
|
||||
```
|
||||
---
|
||||
```
|
||||
|
||||
Appearance
|
||||
|
||||
---
|
||||
Note: Leave an empty line before a horizontal dash.
|
||||
|
||||
### Toggle lists
|
||||
|
||||
- [ ] Unchecked toggle item.
|
||||
- [x] Checked toggle item.
|
||||
|
||||
```
|
||||
- [ ] Unchecked toggle item.
|
||||
- [x] Checked toggle item.
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
To comment out some content, so that it's ignored use HTML comment formatting as follows:
|
||||
```
|
||||
<!-- This is a comment and will not appear-->
|
||||
|
||||
<!--
|
||||
Comments
|
||||
can be
|
||||
multiline.
|
||||
-->
|
||||
```
|
||||
|
||||
|
||||
# Notes {#notes}
|
||||
- For the original Markdown specification see [Markdown specification (John Gruber, 2004)](https://daringfireball.net/projects/markdown/).
|
||||
- For a Markdown formatting guide see [Basic Syntax (markdownguide.org)](https://www.markdownguide.org/basic-syntax/).
|
||||
Loading…
Add table
Reference in a new issue