From ac13f89024dc33e4bce803c5062ee09191bf6f05 Mon Sep 17 00:00:00 2001 From: Ze Yu Date: Tue, 28 Jul 2020 19:04:36 +0800 Subject: [PATCH] Tidy up formattingContents user guide page - Add section on markdown attributes (attributes.mbdf) - Fix a minor spelling error in formattingContents.md - Add missing newline at eof (images.mbdf, tables.mbdf) - Add relative link example using markdown (links.mbdf) - Add starting list number trick example (lists.mbdf) --- docs/userGuide/formattingContents.md | 2 +- docs/userGuide/fullSyntaxReference.md | 1 + docs/userGuide/syntax/attributes.mbdf | 65 +++++++++++++++++++++++++++ docs/userGuide/syntax/images.mbdf | 2 +- docs/userGuide/syntax/links.mbdf | 29 ++++++------ docs/userGuide/syntax/lists.mbdf | 28 +++++++++++- docs/userGuide/syntax/tables.mbdf | 2 +- 7 files changed, 111 insertions(+), 18 deletions(-) create mode 100644 docs/userGuide/syntax/attributes.mbdf diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md index 227168feb2..428ea38214 100644 --- a/docs/userGuide/formattingContents.md +++ b/docs/userGuide/formattingContents.md @@ -15,7 +15,7 @@ -**MarkBind supports a wide collection of Markdown-like basic content formatting syntax** such as text stying, tables, lists, images, links, etc. +**MarkBind supports a wide collection of Markdown-like basic content formatting syntax** such as text styling, tables, lists, images, links, etc. diff --git a/docs/userGuide/fullSyntaxReference.md b/docs/userGuide/fullSyntaxReference.md index 838c53c981..8e91f92d76 100644 --- a/docs/userGuide/fullSyntaxReference.md +++ b/docs/userGuide/fullSyntaxReference.md @@ -17,6 +17,7 @@ links : ['Links', ['basic', 'reader-facing']], footnotes: ['Footnotes', ['basic', 'reader-facing']], images : ['Images', ['basic', 'reader-facing']], + attributes: ['Classes, Attributes & Identifiers', ['basic', 'reader-facing']], tables : ['Tables', ['basic', 'reader-facing']], emoji : ['Emoji', ['basic', 'reader-facing']], icons : ['Icons', ['basic', 'reader-facing']], diff --git a/docs/userGuide/syntax/attributes.mbdf b/docs/userGuide/syntax/attributes.mbdf new file mode 100644 index 0000000000..47fb2020cc --- /dev/null +++ b/docs/userGuide/syntax/attributes.mbdf @@ -0,0 +1,65 @@ +## Classes, Attributes & Identifiers + +Most markdown syntax above this section supports adding classes, attributes and identifiers +using [pandoc](https://pandoc.org/MANUAL.html) syntax without the need for a wrapper html element. + +The syntax is `{.class-name attribute="value" attribute=value #id}`, which is placed at different locations depending +on the type of markdown. + + +markdown + +Apply classes, attributes, identifiers to block level markdown (eg. paragraphs, headings) +by leaving a space before '{' {.text-success #attribute-example} + +#### heading {.text-info} + +--- {.border-danger} + +Apply the same to inline markdown (eg. bold text) by +omitting the **space**{.text-primary .bg-light attribute=value} + + + +Some other types of markdown have **different placements** of the curly group `{...}`. {.mb-4} + +****Unordered and Ordered lists**** + + +markdown + +* Apply to the list item itself like so {.text-success #list-item-id} + * Curly groups after newlines apply to the closest nested list {.text-danger} +{.bg-light} +* Curly groups two lines after the last line apply to the top most list + +{.alert-info} + + + +****Fenced code blocks**** + +Refer to the above [section](../formattingContents.html#line-numbering)! + +For a more detailed guide, see: https://www.npmjs.com/package/markdown-it-attrs + + +Formatting features listed above this section support this syntax for attributes, classes and identifiers. +Those below this section do not. + + + + + +``` +add a space before '{' for block level markdown {.class-name attribute="value" attribute=value #id} + +don't add a space for **inline**{.text-danger} markdown +``` +For a more detailed guide, see: https://www.npmjs.com/package/markdown-it-attrs + + + + + + diff --git a/docs/userGuide/syntax/images.mbdf b/docs/userGuide/syntax/images.mbdf index fc70cacbc9..65b0ea496f 100644 --- a/docs/userGuide/syntax/images.mbdf +++ b/docs/userGuide/syntax/images.mbdf @@ -21,4 +21,4 @@ ![alt text here](https://markbind.org/images/logo-lightbackground.png "title here") - \ No newline at end of file + diff --git a/docs/userGuide/syntax/links.mbdf b/docs/userGuide/syntax/links.mbdf index fc4dfb7275..2687a5c9a5 100644 --- a/docs/userGuide/syntax/links.mbdf +++ b/docs/userGuide/syntax/links.mbdf @@ -30,10 +30,10 @@ MarkBind home is at [here][1]. Links to files of the generated site (e.g., an HTML page or an image file) can be specified either as relative paths or absolute paths. -Absolute paths: +****Absolute paths****
-Links should start with {% raw %}`{{ baseUrl }}`{% endraw %} (which represents the root directory of the project). +Links should start with {% raw %}`{{ baseUrl }}`{% endraw %} (which represents the root directory of the site). {{ icon_example }} Here's how to specify a link to (1) a page, and (2) an image, using the {% raw %}`{{ baseUrl }}`: @@ -47,14 +47,14 @@ To ensure that links in the _markbind/ folder work correctly across {% endraw %}
-Relative paths: +****Relative paths****
{{ icon_example }} Assuming that we have the following folder structure: ``` -c:/course/ - ├── textbook/ +C:\course\ + ├── textbook\ | ├── subsite.md | ├── image.png | └── site.json @@ -65,20 +65,21 @@ c:/course/ Within `textbook/subsite.md`, we can refer to the image using: ```html + +![](image.png) ``` Within `index.md`, we can also display the image using ```html -``` -or by including `subsite.md`: -```html - + +![](textbook/image.png) ``` - - Relative links to resources (e.g. images, hrefs) should be valid relative to the original, included file. In other words, the links should be accessible when traversing starting from the location of the included file. -
- In the example above, image.png is in the same directory as subsite.md. When using relative references, the correct path is image.png and not textbook/image.png. + + + Relative links to resources (e.g. images, hrefs) should be valid **relative to the file where the link is defined**. + + In the example above, `image.png` is in the same directory as `subsite.md`. Thus, the correct path is `image.png` and not `textbook/image.png`.
@@ -98,4 +99,4 @@ MarkBind home is at [here][1]. MarkBind home is at [here](https://markbind.org). - \ No newline at end of file + diff --git a/docs/userGuide/syntax/lists.mbdf b/docs/userGuide/syntax/lists.mbdf index 33a495cabf..38eecb0d19 100644 --- a/docs/userGuide/syntax/lists.mbdf +++ b/docs/userGuide/syntax/lists.mbdf @@ -29,6 +29,32 @@ + +You can also start an ordered list at a particular number by changing the + +first number + +! + + More info on above list types: https://www.markdownguide.org/basic-syntax#lists ****Task lists**** (from GFMD): @@ -82,4 +108,4 @@ - [ ] Item 3 - [x] Item 4 - ( ) Item 5 - \ No newline at end of file + diff --git a/docs/userGuide/syntax/tables.mbdf b/docs/userGuide/syntax/tables.mbdf index 22a24eb483..3bb51056f7 100644 --- a/docs/userGuide/syntax/tables.mbdf +++ b/docs/userGuide/syntax/tables.mbdf @@ -34,4 +34,4 @@ Animal | Trainable?| Price | Remarks Ants | no | 5 | Bees | no | 20 | Cats|yes|100| - \ No newline at end of file +