we/jgdr
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update (added code blocks, internal links, and other minor changes) !publish!

Browse source
This commit is contained in:
constantinos 2023-07-15 14:01:36 +03:00
parent 0eb3cb66de
commit 80d8d47a08
1 changed files with 129 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

201
content/article/markdown-formatting.md
View file

@ -9,23 +9,30 @@ keywords:
- 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 Markdown files can be opened, edited and ready using any text editor, rudimentary or otherwise.
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 Markdown was adopted widely for multiple applications. For example by *GitHub* (for readme files), by R (as R Markdown), for note-taking and collaborative writing (e.g. *Obsidian*, *hackmd.io*, *Zotero*, *Nextcloud*), for chat applications (e.g. *Element*), and also by static website frameworks (e.g. *Hugo* and *Jekyll*).
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 write in Markdown in a rudimentary notepad, it is recommended to use a text editor 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/).
For further resources on Markdown see [notes](#notes).
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 more (see ![Markdown workflow](article:md-workflow)).
# 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
Markdown is a plain text format, intended for digital text.
It's unlike conventional word processors that simulate writing on paper and follow the what-you-see-is-what-you-get (WYSIWYG) concept.
## 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.
@ -68,51 +75,40 @@ Headings make use of the hashtag character, as follows:
## Sub-heading
### Sub-sub-heading
```
Note that a space is required between the hashtag character and the header text.
*Note that a space is required between the hashtag character and the header text.*
## Lists
Markdown bullet lists use the dash/minus symbol as in:
```
- bullet item
```
- bullet 1
- bullet 2
- sub-bullet 2.1
```
Numbered lists start with a number followed by a period as in:
```
1. list item
```
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.
### Bullet lists
Bullet list formatting:
```
- bullet 1
- bullet 2
- sub-bullet 2.1
```
Bullet list appearance:
- bullet 1
- bullet 2
- sub-bullet 2.1
### Numbered lists
Numbered list formatting:
```
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
## Quotes
*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).
@ -132,11 +128,6 @@ Note that:
- 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]
@ -148,30 +139,36 @@ Note that:
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*:
```
![](path/to/image.png)
**Figure 1**: Caption text.
![Image caption.](path/to/image.png)
![Image caption.](path/to/image.png "Optional mouse-over text description.")
```
The examples below use the same graphic put together in Illustrator and exported to:
- SVG (file size: 3KB)
- PNG (file size: 56KB; upscaled 3 times to 2100x900; optimized for text; transparent background)
*Image formatting example*:
```
![](static/sample/jgdr-test-illustration.svg "Optional mouse-over text. Figure 1: Sample illustration in SVG.")
**Figure 1: Sample illustration in SVG.**
![Figure 1: Sample illustration in SVG (vector format).](static/sample/jgdr-test-illustration.svg "(Optional mouse-over text description) This is a SVG vector image.")
![](static/sample/jgdr-test-illustration-3x.png "Optional mouse-over text.")
**Figure 2: Sample illustration in PNG**
![Figure 2: Sample illustration in PNG (raster format); exported from Illustrator: type-optimized, transparent background, size x3.](static/sample/jgdr-test-illustration-3x.png "(Optional mouse-over text) This a PNG raster image.")
```
*Appearance*:
![](static/sample/jgdr-test-illustration.svg "Optional mouse-over text. Figure 1: Sample illustration in SVG.")
**Figure 1**: Sample illustration in SVG (vector format).
![test](static/sample/jgdr-test-illustration-3x.png "Optional mouse-over text. Figure 2: Sample illustration in PNG.")
**Figure 2**: Sample illustration in PNG (raster format); exported from Illustrator: type-optimized, transparent background, size x3.
![Figure 1: Sample illustration in SVG (vector format).](static/sample/jgdr-test-illustration.svg "(Optional mouse-over text description) This is a SVG vector image.")
![Figure 2: Sample illustration in PNG (raster format); exported from Illustrator: type-optimized, transparent background, size x3.](static/sample/jgdr-test-illustration-3x.png "(Optional mouse-over text) This a PNG raster image.")
*Note: to open the full resolution version of an image, right click on an image and select Open image in new tab.*
## Tables
@ -189,29 +186,32 @@ Avoid image formats that are lossy and can introduce artifacts (e.g. JPG).
| This | is | a|
| table | with | content.|
Note: The number of dashes in the second row is arbitrary
---
*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*:
*Formatting*:
```
| Header 1 | Header 2 | Header 3|
|:--|:--:|--:|
| left | center | right|
```
- *Appearance*:
*Appearance*:
| Header 1 | Header 2 | Header 3|
|:--|:--:|--:|
| left | center | right|
### Headerless tables
For a table without headers, leave the initial row empty.
- *Formatting*:
*Formatting*:
```
| | |
@ -220,28 +220,30 @@ For a table without headers, leave the initial row empty.
|without|headers|
```
- *Appearance*:
*Appearance*:
| | |
|-|-|
|A|table|
|without|headers|
## Hyperlinks
## Links
- *Hyperlink formatting*:
### Hyperlinks
*Hyperlink formatting*:
```
[hyperlink caption](https://hyperlink-destination.org)
```
- *Hyperlink appearance*:
*Hyperlink appearance*:
[hyperlink caption](https://hyperlink-destination.org)
Note: Do not omit the `http://` or `https://` part of the URL.
*Note: Do not omit the `http://` or `https://` part of the URL.*
## Internal Links
### Internal links to other sections of this document
To link to another section of the same document, use the hyperlink syntax.
For destination use the heading of the section, in lowercase, replacing spaces with dashes. Prefix that with only one hashtag character, regardless of the depth of the heading.
@ -253,9 +255,24 @@ Syntax:
```
[go to 'What is Markdown'](#what-is-markdown)
```
### Links to other entries of this site
The convention for links to other entries of this project is:
```
![Link caption](itemType:entry-filename)
```
## Footnotes
Examples:
```
![Authors submission guide (issue)](issue:issue-authors-guide)
![Markdown formatting guide (article)](article:markdown-formatting)
```
Appearance:
![Authors submission guide (issue)](issue:issue-authors-guide)
![Markdown formatting guide (article)](article:markdown-formatting)
### 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.`
@ -271,41 +288,81 @@ Here is a sentence with a footnote.[^fn]
[^fn]: This is the text of a footnote, used 3 times.
```
## Embedded content
### 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:
```
![](bib:the-book-id).
```
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:
```
![](bib:f2f08a6f-751c-463a-910b-7742a4e004e5)
```
Appearance:
![](bib:f2f08a6f-751c-463a-910b-7742a4e004e5)
*Note: the formatting convention `![](bib:book-id)` 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 `![My custom text for a library item](bib:book-id)`.*
## 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>).
## 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,
*More importantly, embedding multimedia from other
---
YouTube, and Vimeo videos can be easily embedded using video ids (the last bit of their URLs). Embedded content should contain a caption including...
{{< youtube UEoDJ1v6U6U >}}
**Video 1**: Video caption.
<figcaption>Video 1: Video caption.</figcaption>
{{< vimeo 55073825 >}}
**Video 2**: Video caption.
<figcaption>Video 2: Video caption.</figcaption>
Formatting (replace square brackets with curly brackets):
```
[[< youtube UEoDJ1v6U6U >]]
**Video 1: Description.**
<figcaption>Video 1: Video caption.</figcaption>
[[< vimeo 55073825 >]]
**Video 2: Description.**
<figcaption>Video 2: Video caption.</figcaption>
```
### GitHub Gists
{{< gist cmiltiadis 0c458dcea8b8569398f5988b0151636c >}}
<figcaption>Codegist 1: Gist caption.</figcaption>
Formatting (replace square brackets with curly brackets):
```
[[< gist username gistId >]]
<figcaption>Codegist 1: Gist caption.</figcaption>
```
### Videogame embedding
### Videogame embedding [DRAFT]
Implement Unity WebGL embed described here:
https://michaelcassidy.net/post/hugo-shortcode-for-embedding-unity-webgl-players-updated-with-code/
@ -319,7 +376,7 @@ This should allow embedding games as follows (note: square brackets need to be r
> buildFileName="webgl"
> playerID="" >]]
```
## Unused formatting
## Other formatting
The following includes formatting that might be useful while writing, but has limited application in published material.
@ -349,7 +406,7 @@ Note: Leave an empty line before a horizontal dash.
To comment out some content, so that it's ignored use HTML comment formatting as follows:
```
<!-- this will not appear-->
<!-- This is a comment and will not appear-->
<!--
Comments