diff --git a/docs/_markbind/layouts/userGuide.md b/docs/_markbind/layouts/userGuide.md index f42f912c0b..a3ec5aab02 100644 --- a/docs/_markbind/layouts/userGuide.md +++ b/docs/_markbind/layouts/userGuide.md @@ -38,6 +38,7 @@ * [Syntax Cheat Sheet]({{baseUrl}}/userGuide/syntaxCheatSheet.html) * [`site.json` File]({{baseUrl}}/userGuide/siteJsonFile.html) * [Tips & Tricks]({{baseUrl}}/userGuide/tipsAndTricks.html) + * [Troubleshooting]({{baseUrl}}/userGuide/troubleshooting.html) * [Glossary]({{baseUrl}}/userGuide/glossary.html) diff --git a/docs/index.md b/docs/index.md index 2ec8ca1158..6ff1b63823 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,11 +6,11 @@

**MarkBind**

- +
++**Generate _more dynamic_ websites from Markdown text.**++ Optimized for creating text-heavy websites %%e.g., eLearning websites, online instruction manuals, project documentation etc.%% - +
Get Started diff --git a/docs/userGuide/addingPages.md b/docs/userGuide/addingPages.md index 88f526f0ab..7e7ab2f59f 100644 --- a/docs/userGuide/addingPages.md +++ b/docs/userGuide/addingPages.md @@ -14,11 +14,11 @@ # {{ title }} - +
**It is easy to add files to a MarkBind site as any file inside the {{ tooltip_root_directory }} becomes a part of the generated website.** - +
diff --git a/docs/userGuide/components/imagesAndDiagrams.md b/docs/userGuide/components/imagesAndDiagrams.md index ab8c4e3111..611164b721 100644 --- a/docs/userGuide/components/imagesAndDiagrams.md +++ b/docs/userGuide/components/imagesAndDiagrams.md @@ -16,11 +16,11 @@ # Image & Diagram Components - +
The image components here provide **convenient syntax & styling abstractions** on top of raw HTML and Markdown images. Diagrams, in the form of **inline PlantUML components** are also supported. - +
{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/components/others.md b/docs/userGuide/components/others.md index 19ad8dad9e..aee2cfd4cf 100644 --- a/docs/userGuide/components/others.md +++ b/docs/userGuide/components/others.md @@ -16,10 +16,10 @@ # Other Components - +
This page lists some other components that may be useful in creating education websites. For now, there are only question and quiz components. - +
{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/components/popups.md b/docs/userGuide/components/popups.md index d1e762638f..d277ebb36a 100644 --- a/docs/userGuide/components/popups.md +++ b/docs/userGuide/components/popups.md @@ -16,10 +16,10 @@ # Pop-Up Components - +
The components in this page can be used to easily create **various forms of pop-ups** that are activated on some user action (e.g., hovering over some text). This may be useful for showing additional information related to some specific area or span of content. - +
{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/components/presentation.md b/docs/userGuide/components/presentation.md index b63d63c5e4..cefb51591b 100644 --- a/docs/userGuide/components/presentation.md +++ b/docs/userGuide/components/presentation.md @@ -16,10 +16,10 @@ # Presentational Components - +
The components in this page are the core **presentational** components you may want to use. Panels and tabs can be used to **organise content sections**, while badges and boxes can **highlight small, specific pieces of information**. - +
{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index 29d041a0a9..b7a2af1dd5 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -14,10 +14,10 @@ # {{ title }} - +
**A site generated by MarkBind can be deployed by simply uploading the generated files to any Web server.** In addition, MarkBind provides several convenient deployment options. - +
## Generic steps for deploying a MarkBind site diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md index c1e36e1285..86bbcf99f9 100644 --- a/docs/userGuide/formattingContents.md +++ b/docs/userGuide/formattingContents.md @@ -14,11 +14,11 @@ # {{ title }} - +
**MarkBind supports a wide collection of Markdown-like basic content formatting syntax** such as text styling, tables, lists, images, links, etc. - +
{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/glossary.md b/docs/userGuide/glossary.md index 8f477d7413..81638866e5 100644 --- a/docs/userGuide/glossary.md +++ b/docs/userGuide/glossary.md @@ -5,7 +5,7 @@ #### Live Preview :fas-sync: - +
**_Live preview_** is: - Regeneration of affected content upon any change to source files, then reloading the updated site in the Browser. @@ -16,4 +16,4 @@ Use [the `serve` command](cliCommands.html#serve-command) to launch a live preview. - +
diff --git a/docs/userGuide/makingTheSiteSearchable.md b/docs/userGuide/makingTheSiteSearchable.md index 28c1621238..79605b2f80 100644 --- a/docs/userGuide/makingTheSiteSearchable.md +++ b/docs/userGuide/makingTheSiteSearchable.md @@ -16,10 +16,10 @@ # {{ title }} - +
**MarkBind comes with an in-built _site search_ facility** with the option to use third-party search services as well. - +
**All markdown and html headings of levels 1-3 are captured in the search index** by default. You can change this setting using the [`headingIndexLevel` property of the `site.json`](siteJsonFile.html#headingindexinglevel). diff --git a/docs/userGuide/markBindInTheProjectWorkflow.md b/docs/userGuide/markBindInTheProjectWorkflow.md index 2356a75e95..d8fc23958f 100644 --- a/docs/userGuide/markBindInTheProjectWorkflow.md +++ b/docs/userGuide/markBindInTheProjectWorkflow.md @@ -13,10 +13,10 @@ # {{ title }} - +
As **MarkBind is especially optimized as a project documentation tool**, it integrates well with the workflow of software projects. - +
#### Authoring Workflow diff --git a/docs/userGuide/markBindSyntaxOverview.md b/docs/userGuide/markBindSyntaxOverview.md index 80234e8487..0677fdb226 100644 --- a/docs/userGuide/markBindSyntaxOverview.md +++ b/docs/userGuide/markBindSyntaxOverview.md @@ -14,10 +14,10 @@ # {{ title }} - +
**A MarkBind source file may contain a mix of several popular syntax schemes** used in creating web pages. MarkBind source file can be as simple as basic Markdown, and you can use progressively more complicated syntax to create progressively more sophisticated Web pages while optimizing other aspects such as content reuse. - +
Given below is an overview of the syntax schemes supported by MarkBind. diff --git a/docs/userGuide/plugins/tags.md b/docs/userGuide/plugins/tags.md index f9d923bce5..2505dbacfc 100644 --- a/docs/userGuide/plugins/tags.md +++ b/docs/userGuide/plugins/tags.md @@ -67,7 +67,7 @@ Alternatively, you can specify tags to render for a page in the front matter. ```
- +
```html

System.out.println("Hello world");

@@ -79,7 +79,7 @@ Alternatively, you can specify tags to render for a page in the front matter. tags: ["language--java"] ``` - +
Tags in `site.json` will be merged with the ones in the front matter, and are processed after front matter tags. See [Hiding Tags](../tweakingThePageStructure.html#hiding-tags) for more information. @@ -143,7 +143,7 @@ Using `-` at the start of a tag hides all tags matching the expression. This is This only works because tags are processed left to right, so all `language--*` tags are hidden before `language--C#`. Tags in `site.json` are processed after tags in ``. - +
```html # Print 'Hello world' @@ -165,4 +165,4 @@ This only works because tags are processed left to right, so all `language--*` t } } ``` - +
diff --git a/docs/userGuide/reusingContents.md b/docs/userGuide/reusingContents.md index e1e5857362..e9be9f7227 100644 --- a/docs/userGuide/reusingContents.md +++ b/docs/userGuide/reusingContents.md @@ -14,10 +14,10 @@ # {{ title }} - +
**MarkBind is highly-optimized for content reuse**. It offers several mechanisms to provide readers with many variations of the content while minimizing duplication at source file level. As a result, instead of creating a one-size-fits-all site, MarkBind can create a site in which readers can chart their own path of reading. - +
diff --git a/docs/userGuide/siteJsonFile.md b/docs/userGuide/siteJsonFile.md index 9b38e3966c..85159a2f89 100644 --- a/docs/userGuide/siteJsonFile.md +++ b/docs/userGuide/siteJsonFile.md @@ -7,10 +7,10 @@ # `site.json` File - +
The `site.json` file {{ tooltip_root_directory }} is used to configure various aspects of a MarkBind website. - +
Here is a typical `site.json` file: @@ -131,14 +131,14 @@ _(Optional)_ **The styling options to be applied to the site.** This includes: * **`externalScripts`**: An array of external scripts to be referenced on the page. Scripts referenced will be run before the layout script. * **`frontMatter`**: Specifies properties to add to the front matter of a page or glob of pages. Overrides any existing properties if they have the same name, and overrides any front matter properties specified in `globalOverride`. - +
Note: Page properties that are defined in `site.json` for a particular page will override those defined in the front matter of the page. - +
- +
Note: If multiple **`src`** (pages) or **`glob`** (globs) attributes match a file, MarkBind will merge properties from all entries. If there are conflicting properties, pages are given priority over globs. If there are multiple matching glob entries, the last entry is given priority. @@ -177,7 +177,7 @@ The following properties will apply to `index.md`:
- + #### **`pagesExclude`** diff --git a/docs/userGuide/syntax/attributes.md b/docs/userGuide/syntax/attributes.md index 18739a39de..c68020afad 100644 --- a/docs/userGuide/syntax/attributes.md +++ b/docs/userGuide/syntax/attributes.md @@ -50,7 +50,7 @@ Those below this section do not. - +
``` add a space before '{' for block level markdown {.class-name attribute="value" attribute=value #id} @@ -58,9 +58,9 @@ add a space before '{' for block level markdown {.class-name attribute="value" a 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/badges.md b/docs/userGuide/syntax/badges.md index f5990091a9..d188c43b57 100644 --- a/docs/userGuide/syntax/badges.md +++ b/docs/userGuide/syntax/badges.md @@ -52,7 +52,7 @@ Headings: - +
```markdown Primary @@ -61,9 +61,9 @@ Headings: Difficulty Level 4 ``` - +
- +
Primary Success @@ -71,4 +71,4 @@ Headings: Difficulty Level 4 ##### Feature Y stable {.no-index} - +
diff --git a/docs/userGuide/syntax/blockquotes.md b/docs/userGuide/syntax/blockquotes.md index 7eae6eebda..7bc6145ecc 100644 --- a/docs/userGuide/syntax/blockquotes.md +++ b/docs/userGuide/syntax/blockquotes.md @@ -29,7 +29,7 @@ Nested blockquote More info: https://www.markdownguide.org/basic-syntax#blockquotes-1 - +
``` > Blockquote, first paragraph @@ -37,11 +37,11 @@ Nested blockquote > Second paragraph >> Nested blockquote ``` - - +
+
> Blockquote, first paragraph > > Second paragraph >> Nested blockquote - +
diff --git a/docs/userGuide/syntax/boxes.md b/docs/userGuide/syntax/boxes.md index 96dfb03e03..c8b8597445 100644 --- a/docs/userGuide/syntax/boxes.md +++ b/docs/userGuide/syntax/boxes.md @@ -233,15 +233,15 @@ no-backgound | `Boolean` | `false` | Removes background, except if styled by `ba no-icon | `Boolean` | `false` | Removes icon, except if icon is displayed via `icon` option. - +
```html warning ``` - - +
+
default @@ -267,4 +267,4 @@ no-icon | `Boolean` | `false` | Removes icon, except if icon is displayed via `i definition - +
diff --git a/docs/userGuide/syntax/code.md b/docs/userGuide/syntax/code.md index 0b10e447ae..4561f2220b 100644 --- a/docs/userGuide/syntax/code.md +++ b/docs/userGuide/syntax/code.md @@ -219,7 +219,7 @@ or the java code `public static void main(String[] args)`{.java}. - +
```` ```xml @@ -231,8 +231,8 @@ or the java code `public static void main(String[] args)`{.java}. ``` `goo`{.xml} ``` - - +
+
```xml @@ -241,4 +241,4 @@ or the java code `public static void main(String[] args)`{.java}. ``` Syntax coloring for inline code: `goo`{.xml} too! - +
diff --git a/docs/userGuide/syntax/dates.md b/docs/userGuide/syntax/dates.md index 0f824ce098..53087c0d59 100644 --- a/docs/userGuide/syntax/dates.md +++ b/docs/userGuide/syntax/dates.md @@ -73,9 +73,9 @@ YYYY | 2019 Full formatting reference available [here](https://momentjs.com/docs/#/displaying/format/). {{ icon_example }} - +
- +
{{ njblock('set base1 = "2019-08-12"') }}
@@ -87,21 +87,21 @@ Full formatting reference available [here](https://momentjs.com/docs/#/displayin {{ njcode('base1 | date(format2, 10)') }} ``
 - - +
+
Mon 12 Aug
12 08 2019
22 08 2019
Thu 22/08 - +
 +
- +
-{{ njcode('"2019-08-12" | date("DD.MM.YYYY", 10)') }} ``
+{{ njcode('"2019-08-12" | date("DD.MM.YYYY", 10)') }}
{{ "2019-08-12" | date("DD.MM.YYYY", 10) }} - - +
diff --git a/docs/userGuide/syntax/diagrams.md b/docs/userGuide/syntax/diagrams.md index 6c647b95fc..52c8eb9aa4 100644 --- a/docs/userGuide/syntax/diagrams.md +++ b/docs/userGuide/syntax/diagrams.md @@ -15,7 +15,7 @@ must be installed to use this feature**
- +
``` @@ -31,19 +31,19 @@ return success @enduml ``` - +
- +
 - +
Alternatively, a PlantUML diagram can be specified in a separate `.puml` file and inserted into a page using a `` tag. - +
`diagrams/sequence.puml`: ``` @@ -63,11 +63,11 @@ in another file: ```html ``` - +
- +
- +
 @@ -78,7 +78,7 @@ The full PlantUML syntax reference can be found at plantuml.com/guide - +
**Sequence Diagram**:
@@ -113,7 +113,7 @@ The full PlantUML syntax reference can be found at plantuml.com/guide **Archimate Diagram**:
- +

@@ -126,7 +126,7 @@ name | `string` | The name of the output file. src | `string` | The URL of the diagram if your diagram is in another `.puml` file.
The URL can be specified as absolute or relative references. More info in: _[Intra-Site Links]({{baseUrl}}/userGuide/formattingContents.html#intraSiteLinks)_ width | `string` | The width of the diagram in pixels.
If both width and height are specified, width takes priority over height. It is to maintain the diagram's aspect ratio. - +

``` @@ -137,9 +137,9 @@ bob -> bob ++ : self call ``` - - +
+
- +
diff --git a/docs/userGuide/syntax/dropdowns.md b/docs/userGuide/syntax/dropdowns.md index b4c652da93..f7218f3726 100644 --- a/docs/userGuide/syntax/dropdowns.md +++ b/docs/userGuide/syntax/dropdowns.md @@ -81,7 +81,7 @@ type | `String` | `default` | Supports: `default`, `primary`, `danger`, `info`, - +
```markdown @@ -91,9 +91,9 @@ type | `String` | `default` | Supports: `default`, `primary`, `danger`, `info`,
  • Separated link
    •  ``` - +
    - +
  • Action
    • @@ -128,4 +128,4 @@ type | `String` | `default` | Supports: `default`, `primary`, `danger`, `info`,     Right
    -     + diff --git a/docs/userGuide/syntax/embeds.md b/docs/userGuide/syntax/embeds.md index 9dc70acdff..07ce28a5dd 100644 --- a/docs/userGuide/syntax/embeds.md +++ b/docs/userGuide/syntax/embeds.md @@ -8,18 +8,18 @@ Here are three ways of embedding YouTube videos and one example of how it will l - +
    ```markdown @[youtube](v40b3ExbM0c) @[youtube](http://www.youtube.com/watch?v=v40b3ExbM0c) @[youtube](http://youtu.be/v40b3ExbM0c) ``` - - +
    +
    @[youtube](v40b3ExbM0c) - +
     More media blocks, embedding services and additional options can be found in [Markdown-it documentation](https://github.com/rotorz/markdown-it-block-embed). @@ -35,7 +35,7 @@ Here is an example of embedding a PowerPoint slide deck: - +
    ```markdown @[youtube](v40b3ExbM0c) @@ -44,9 +44,9 @@ Here is an example of embedding a PowerPoint slide deck: @[powerpoint](https://onedrive.live.com/embed?cid=A5AF047C4CAD67AB&resid=A5AF047C4CAD67AB%212070&authkey=&em=2) ``` - +
    - +
    Embedded YouTube video: @@ -56,4 +56,4 @@ Embedded slide deck: @[powerpoint](https://onedrive.live.com/embed?cid=A5AF047C4CAD67AB&resid=A5AF047C4CAD67AB%212070&authkey=&em=2) - \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/userGuide/syntax/emoji.md b/docs/userGuide/syntax/emoji.md index 9c4b65065d..f3d02b9094 100644 --- a/docs/userGuide/syntax/emoji.md +++ b/docs/userGuide/syntax/emoji.md @@ -14,14 +14,14 @@ %%{{ icon_info }} [the list of supported emoji](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md).%% - +
    ```markdown :+1: :exclamation: :x: :construction: ``` - +
    - +
    :+1: :exclamation: :x: :construction: - \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/userGuide/syntax/footnotes.md b/docs/userGuide/syntax/footnotes.md index bfde77c778..65cf627bba 100644 --- a/docs/userGuide/syntax/footnotes.md +++ b/docs/userGuide/syntax/footnotes.md @@ -1,6 +1,6 @@ ## Footnotes - +
    markdown @@ -23,7 +23,7 @@ note.] - +
    @@ -32,7 +32,7 @@ Normal footnotes won't work when used inside the attributes of markbind componen For example, it won't work in the `header` attribute of [panels](../components/presentation.html#panels). - +
    ```html **Normal footnotes:** @@ -44,7 +44,7 @@ Here is a footnote reference,[^1] and another.[^longnote] Subsequent paragraphs are indented to show that they belong to the previous footnote. ``` - - +
    +
    1 + 1 = 2 ^[Math] - +
    diff --git a/docs/userGuide/syntax/frontmatter.md b/docs/userGuide/syntax/frontmatter.md index 484dfdb95b..c65a086758 100644 --- a/docs/userGuide/syntax/frontmatter.md +++ b/docs/userGuide/syntax/frontmatter.md @@ -30,7 +30,7 @@ Should you need more expressive formatting, or encounter any issues when formatt - +
    ```html @@ -38,4 +38,4 @@ Should you need more expressive formatting, or encounter any issues when formatt pageNav: 2 ``` - +
    diff --git a/docs/userGuide/syntax/headings.md b/docs/userGuide/syntax/headings.md index a4a212148d..e245181cf0 100644 --- a/docs/userGuide/syntax/headings.md +++ b/docs/userGuide/syntax/headings.md @@ -18,17 +18,17 @@ If the heading text is `Foo Bar (Goo)`, the ID of the generated anchor will be ` Alternative syntax, more info: https://www.markdownguide.org/basic-syntax#headings - +
    ```markdown ### Heading level 3 ... ###### Heading level 6 ``` - - +
    +
    ### Heading level 3 ... ###### Heading level 6 - \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/userGuide/syntax/horizontalrules.md b/docs/userGuide/syntax/horizontalrules.md index 83edd8e036..886f8e5816 100644 --- a/docs/userGuide/syntax/horizontalrules.md +++ b/docs/userGuide/syntax/horizontalrules.md @@ -91,16 +91,16 @@ Add a comibnation of the above classes to further customize the style of a horiz     - +
    ```markdown ***** ----- ______________ ``` - +
    - +
    ---- - +
    diff --git a/docs/userGuide/syntax/icons.md b/docs/userGuide/syntax/icons.md index a055f873a8..82508de781 100644 --- a/docs/userGuide/syntax/icons.md +++ b/docs/userGuide/syntax/icons.md @@ -36,16 +36,16 @@ Please use the new `:prefix-name:` syntax instead. 1. Insert the name for the icon enclosed within colons to get the icon in your page.
    `Move to the right!`:glyphicon-hand-right: → Move to the right! :glyphicon-hand-right: - +
    :glyphicon-hand-right: :fab-github: :fas-home: - +
    - +
    :glyphicon-hand-right: :fab-github: :fas-home: %%:glyphicon-hand-right: :fab-github: :fas-home:%% :glyphicon-hand-right: :fab-github: :fas-home: - +
    ###### Using Octicons diff --git a/docs/userGuide/syntax/images.md b/docs/userGuide/syntax/images.md index 864c16a164..5ff078f10a 100644 --- a/docs/userGuide/syntax/images.md +++ b/docs/userGuide/syntax/images.md @@ -12,17 +12,17 @@ - +
    ```markdown ![alt text here](https://markbind.org/images/logo-lightbackground.png "title here") ``` - +
    - +
    ![alt text here](https://markbind.org/images/logo-lightbackground.png "title here") - +
    MarkBind also supports the `=Wx` shorthand for specifying image width: diff --git a/docs/userGuide/syntax/includes.md b/docs/userGuide/syntax/includes.md index 426fe49d08..076275c7ce 100644 --- a/docs/userGuide/syntax/includes.md +++ b/docs/userGuide/syntax/includes.md @@ -4,10 +4,10 @@ ## Includes - +
    **MarkBind has a powerful `` mechanism** which allows you to create documents by combining other content fragments. - +
    **You can use `` tag to include another markdown or HTML document into the current document.** @@ -23,6 +23,12 @@ Tip 3. ... **You can `` a fragment of a file** by specifying the `#fragment-id` at the end of the `src` attribute value, provided the fragment is wrapped in a `
    `/``/`` tag with the matching `id`. + + +Choose `
    ` over `` when wrapping block-level elements, to prevent invalid HTML markup which causes [hydration issues](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch). + + +
    {{ icon_example }} Including a fragment from a file: @@ -254,11 +260,11 @@ It needs to be used as follows:
    - +
    ```markdown 5 ``` - +
    diff --git a/docs/userGuide/syntax/keywords.md b/docs/userGuide/syntax/keywords.md index eb2af3c3f6..6587a1464b 100644 --- a/docs/userGuide/syntax/keywords.md +++ b/docs/userGuide/syntax/keywords.md @@ -39,9 +39,9 @@ This is good for catching regressions. ```
    - +
    ```html regress ``` - +
    diff --git a/docs/userGuide/syntax/lineBreaks.md b/docs/userGuide/syntax/lineBreaks.md index a78974a59d..b98c56a792 100644 --- a/docs/userGuide/syntax/lineBreaks.md +++ b/docs/userGuide/syntax/lineBreaks.md @@ -12,10 +12,10 @@ This will not be in a new line. Alternate syntax: https://www.markdownguide.org/basic-syntax#line-breaks - +
    ```markdown This is the second sentence.
    This should be on a new line. ``` - \ No newline at end of file +
    \ No newline at end of file diff --git a/docs/userGuide/syntax/links.md b/docs/userGuide/syntax/links.md index 59f6566a46..ae2c74f0e9 100644 --- a/docs/userGuide/syntax/links.md +++ b/docs/userGuide/syntax/links.md @@ -165,7 +165,7 @@ However, if you wish to disable this feature **entirely**, you may simply modify
    - +
    ```markdown MarkBind home is at [here](https://markbind.org). @@ -174,9 +174,9 @@ MarkBind home is at [here][1]. [1]: https://markbind.org ``` - +
    - +
    MarkBind home is at [here](https://markbind.org). - +
    diff --git a/docs/userGuide/syntax/lists.md b/docs/userGuide/syntax/lists.md index 9716301492..45e341390d 100644 --- a/docs/userGuide/syntax/lists.md +++ b/docs/userGuide/syntax/lists.md @@ -59,7 +59,7 @@ first number ****Task lists**** (from GFMD): - +
    markdown @@ -70,7 +70,7 @@ first number - [ ] Item 3 - +
    ****Radio-button lists:**** @@ -85,7 +85,7 @@ first number     - +
    ```markdown 1. Item 1 @@ -97,8 +97,8 @@ first number - [x] Item 4 - ( ) Item 5 ``` - - +
    +
    1. Item 1 1. Sub item 1.1 @@ -108,4 +108,4 @@ first number - [ ] Item 3 - [x] Item 4 - ( ) Item 5 - +
    diff --git a/docs/userGuide/syntax/mathformulae.md b/docs/userGuide/syntax/mathformulae.md index 42b9b1d701..c02eb95163 100644 --- a/docs/userGuide/syntax/mathformulae.md +++ b/docs/userGuide/syntax/mathformulae.md @@ -54,7 +54,7 @@ If your equation requires special Nunjucks tags like {% raw %}`{{`{% endraw %} o More info on allowed symbols: https://katex.org/docs/support_table.html - +
    ```markdown @@ -67,8 +67,8 @@ Solve the following simultaneous equations: Euler's equation \( e^{i\pi}+1=0 \) is a beautiful equation. ``` - - +
    +
    Solve the following simultaneous equations: @@ -78,4 +78,4 @@ Solve the following simultaneous equations: Euler's equation \( e^{i\pi}+1=0 \) is a beautiful equation. - +
    diff --git a/docs/userGuide/syntax/modals.md b/docs/userGuide/syntax/modals.md index 4573e5871c..10e878dfa6 100644 --- a/docs/userGuide/syntax/modals.md +++ b/docs/userGuide/syntax/modals.md @@ -51,7 +51,7 @@ large | `Boolean` | `false` | Creates a [large Modal](https://getbootstrap.com/d center | `Boolean` | `false` | Vertically centers the modal (in addition to the horizontal centering by default). backdrop | `Boolean` | `true` | Enables closing the Modal by clicking on the backdrop. - +
    ```html Click here to open a modal. @@ -59,12 +59,12 @@ Click here to open a modal Modal content ``` - +
    - +
    Hover here to open a modal. Modal content - +
    diff --git a/docs/userGuide/syntax/navBars.md b/docs/userGuide/syntax/navBars.md index 00f790f2ed..97cacde8bb 100644 --- a/docs/userGuide/syntax/navBars.md +++ b/docs/userGuide/syntax/navBars.md @@ -93,7 +93,7 @@ Name | Description `exact` | Highlights link if URL in address bar exactly matches link. `none` | No highlighting. - +
    ```html @@ -111,9 +111,9 @@ Name | Description ``` - +
    - +
    @@ -157,7 +157,7 @@ Name | Description - +
    ****Mobile page and site navigation menus**** diff --git a/docs/userGuide/syntax/pageNavigationMenus.md b/docs/userGuide/syntax/pageNavigationMenus.md index bcc7db7b6f..720b32372c 100644 --- a/docs/userGuide/syntax/pageNavigationMenus.md +++ b/docs/userGuide/syntax/pageNavigationMenus.md @@ -47,7 +47,7 @@ Then, in your [layout file]({{baseUrl}}/userGuide/tweakingThePageStructure.html# - +
    You can see an example of a Page Navigation Bar ==on the right side== of this page. - +
    diff --git a/docs/userGuide/syntax/panels.md b/docs/userGuide/syntax/panels.md index 85d74166e5..2ef955cbec 100644 --- a/docs/userGuide/syntax/panels.md +++ b/docs/userGuide/syntax/panels.md @@ -207,16 +207,16 @@ preload | `Boolean` | `false` | Whether the content is loaded immediately from ` src | `String` | | The url to the remote page to be loaded as the content of the panel. type | `String` | `light` | The type or color scheme of the panel (single).
    Supports: `light`, `dark`, `primary`, `secondary`, `info`, `success`, `warning`, `danger`, `seamless`, `minimal`. - +
    ```html ... ``` - +
    - +
    ... @@ -250,4 +250,4 @@ type | `String` | `light` | The type or color scheme of the panel (single).
    S - +
    diff --git a/docs/userGuide/syntax/paragraphs.md b/docs/userGuide/syntax/paragraphs.md index 269d4c442a..798524eae3 100644 --- a/docs/userGuide/syntax/paragraphs.md +++ b/docs/userGuide/syntax/paragraphs.md @@ -11,11 +11,11 @@ This is another paragraph. This is the second sentence.     - +
    ```markdown This is the first paragraph. This is another paragraph. This is the second sentence. ``` - +
    diff --git a/docs/userGuide/syntax/pictures.md b/docs/userGuide/syntax/pictures.md index 2448d90511..f40fada482 100644 --- a/docs/userGuide/syntax/pictures.md +++ b/docs/userGuide/syntax/pictures.md @@ -24,18 +24,18 @@ src | `string` | | **This must be specified.**
    The URL of the image.
    The U width | `string` | | The width of the image in pixels.
    If both width and height are specified, width takes priority over height. It is to maintain the image's aspect ratio. eager | `boolean` | false | The `` component lazy loads its images by default.
    If you want to eagerly load the images, simply specify this attribute. - +
    ```html MarkBind Logo ``` - +
    - +
    MarkBind Logo - +
    diff --git a/docs/userGuide/syntax/popovers.md b/docs/userGuide/syntax/popovers.md index d5814dc41d..657d3374af 100644 --- a/docs/userGuide/syntax/popovers.md +++ b/docs/userGuide/syntax/popovers.md @@ -33,41 +33,41 @@

    Trigger

    -

    +

    -

    +

    Markdown

    -

    +

    -

    +

    Content using slot

    -

    +

    This is a long content...
    -

    +

    Content using src

    -

    +

    This is loaded from a .html file -

    -

    +

    +
    This is loaded from a .md file -

    +

    Wrap Text

    -

    +

    What do you say -

    +
    @@ -110,7 +110,7 @@ If multiple of these are used, MarkBind will prioritise in the following order: 1. `src` attribute - +
    ```html Hover over the keyword to see the popover. @@ -123,9 +123,9 @@ description :+1:
    ``` -     + - +
    Hover over the keyword to see the popover. @@ -136,4 +136,4 @@ description :+1:
    -     + diff --git a/docs/userGuide/syntax/questions.md b/docs/userGuide/syntax/questions.md index 71020983c4..13a474b737 100644 --- a/docs/userGuide/syntax/questions.md +++ b/docs/userGuide/syntax/questions.md @@ -313,7 +313,7 @@ intro | `String` | `''` | Quiz intro markup above the question count. intro | Slot | `Click start to begin` | Quiz intro markup. Overrides the `intro` attribute if both are present. - +
    ```html { heading="MCQ and Checkbox questions" } @@ -331,9 +331,9 @@ intro | Slot | `Click start to begin` | Quiz intro markup. Overrides the `intro` ... ``` - +
    - +
    - +
    diff --git a/docs/userGuide/syntax/searchBars.md b/docs/userGuide/syntax/searchBars.md index f60c75fd99..87afc38bd8 100644 --- a/docs/userGuide/syntax/searchBars.md +++ b/docs/userGuide/syntax/searchBars.md @@ -2,10 +2,10 @@ The `searchbar` component allows users to search all headings within any page on the site. - +
    - +
    ```html @@ -21,14 +21,14 @@ To use the searchbar within a navbar, add the following markup to your file. The ``` - - +
    +
    Enter a search term (eg. 'search bar') to see the search result dropdown.
    - +
     ****Options**** @@ -53,9 +53,9 @@ See: [User Guide: Site Configuration → enableSearch]({{ baseUrl }}/userGuide/s %%{{ icon_info }} Related topic: [User Guide: Using Plugins → Algolia: Enabling Algolia DocSearch]({{ baseUrl }}/userGuide/usingPlugins.html#algolia-enabling-algolia-docsearch).%% - +
    - +
    ```html @@ -68,9 +68,9 @@ See: [User Guide: Site Configuration → enableSearch]({{ baseUrl }}/userGuide/s ``` - +
    - +
    - +
    diff --git a/docs/userGuide/syntax/tables.md b/docs/userGuide/syntax/tables.md index 3bb51056f7..e556e1991b 100644 --- a/docs/userGuide/syntax/tables.md +++ b/docs/userGuide/syntax/tables.md @@ -16,7 +16,7 @@ Cats|yes|100| More info: https://www.markdownguide.org/extended-syntax#tables - +
    ```markdown Animal | Trainable?| Price | Remarks @@ -25,13 +25,13 @@ Ants | no | 5 | Bees | no | 20 | Cats|yes|100| ``` - +
    - +
    Animal | Trainable?| Price | Remarks :----- | :-------: | ----: | ---- Ants | no | 5 | Bees | no | 20 | Cats|yes|100| - +
    diff --git a/docs/userGuide/syntax/tabs.md b/docs/userGuide/syntax/tabs.md index 04bcab1389..2b9c328f62 100644 --- a/docs/userGuide/syntax/tabs.md +++ b/docs/userGuide/syntax/tabs.md @@ -52,7 +52,7 @@ disabled | `Boolean` | `false` | Whether Tab Group is clickable and can be activ Tabs, tab group and individual tab can be omitted during printing by adding bootstrap's display property `class="d-print-none"` to the respective components. - +
    ```html @@ -72,9 +72,9 @@ Tabs, tab group and individual tab can be omitted during printing by adding boot ``` - +
    - +
    @@ -92,4 +92,4 @@ Tabs, tab group and individual tab can be omitted during printing by adding boot - +
    diff --git a/docs/userGuide/syntax/tags.md b/docs/userGuide/syntax/tags.md index 5a7cecaacc..a60cf3b1f8 100644 --- a/docs/userGuide/syntax/tags.md +++ b/docs/userGuide/syntax/tags.md @@ -1,5 +1,5 @@ - +
    - +
    diff --git a/docs/userGuide/syntax/textStyles.md b/docs/userGuide/syntax/textStyles.md index 2588b4fba7..578dd61f7e 100644 --- a/docs/userGuide/syntax/textStyles.md +++ b/docs/userGuide/syntax/textStyles.md @@ -2,14 +2,14 @@ Markdown text styles: - +
    markdown **Bold**, _Italic_, ___Bold and Italic___, `Inline Code` - +
    Additional syntax from GFMD: @@ -22,7 +22,7 @@ Additional syntax from GFMD: Syntax added by MarkBind: - +
    markdown @@ -30,19 +30,19 @@ Syntax added by MarkBind: ->Center-align<- - +
    Alternative syntax: https://www.markdownguide.org/basic-syntax#emphasis - +
    ```markdown **Bold**, _Italic_, ___Bold and Italic___, `Inline Code` ~~Strike through~~, ****Super Bold****, !!Underline!!, ==Highlight==, %%Dim%%, ++Large++, --Small--, Super^script^, Sub~script~ ``` - - +
    +
    **Bold**, _Italic_, ___Bold and Italic___, `Inline Code` ~~Strike through~~, ****Super Bold****, !!Underline!!, ==Highlight==, %%Dim%%, ++Large++, --Small--, Super^script^, Sub~script~ - +
    diff --git a/docs/userGuide/syntax/thumbnails.md b/docs/userGuide/syntax/thumbnails.md index 987833e994..028503dece 100644 --- a/docs/userGuide/syntax/thumbnails.md +++ b/docs/userGuide/syntax/thumbnails.md @@ -35,13 +35,13 @@ text | `string` | | The text to use in the thumbnail, [icons]({{baseUrl}}/userGu If both `text` and `src` are specified, `src` will take higher priority. - +
    ```html ``` - +
    - +
    - +
    diff --git a/docs/userGuide/syntax/tooltips.md b/docs/userGuide/syntax/tooltips.md index 74aa76bc50..65e716c216 100644 --- a/docs/userGuide/syntax/tooltips.md +++ b/docs/userGuide/syntax/tooltips.md @@ -66,14 +66,14 @@ content | `String` | `''` | Text content of the tooltip. placement | `String` | `top` | How to position the tooltip.
    Supports: `top`, `left`, `right`, `bottom`. - +
    ```html Hover here to see a tooltip. ``` - +
    - +
    Hover here to see a tooltip. - +
    diff --git a/docs/userGuide/syntax/tree.md b/docs/userGuide/syntax/tree.md index 59e2d7ded2..a186b192be 100644 --- a/docs/userGuide/syntax/tree.md +++ b/docs/userGuide/syntax/tree.md @@ -93,7 +93,7 @@ Currently, Pop-Ups(tooltip/trigger) are !!not!! supported within a `tree` compon - +
    ```html @@ -105,9 +105,9 @@ C:/course/ site.json ``` - +
    - +
    C:/course/ textbook/ @@ -116,4 +116,4 @@ C:/course/ reading.md site.json - +
    diff --git a/docs/userGuide/syntax/variables.md b/docs/userGuide/syntax/variables.md index ac91fa795c..4840fe8a27 100644 --- a/docs/userGuide/syntax/variables.md +++ b/docs/userGuide/syntax/variables.md @@ -4,10 +4,10 @@ ## Variables - +
    **Nunjucks [variables](https://mozilla.github.io/nunjucks/templating.html#set) are ideal for reusing small bits of code** in multiple places; you can define a variable to represent the code bit in question and reuse it anywhere in the site by referring to the variable instead of duplicating the code bit. - +
    MarkBind does not aim to alter the already robust variable features of nunjucks, but provides several extensions to it. @@ -179,15 +179,15 @@ Only `.json` and `.csv` files are supported for now. - +
    Global variables: `_markbind/variables.md`: ```html -2018 +2018 ``` `The year was {% raw %}{{ year }}{% endraw %}.` - +
    diff --git a/docs/userGuide/themes.md b/docs/userGuide/themes.md index fcd424e756..8734f848aa 100644 --- a/docs/userGuide/themes.md +++ b/docs/userGuide/themes.md @@ -13,11 +13,11 @@ # {{ title }} - +
    **MarkBind supports the ability to style your website with a variety of bootstrap themes.** - +
    #### Specifying a Theme diff --git a/docs/userGuide/tipsAndTricks.md b/docs/userGuide/tipsAndTricks.md index 21129c406b..7eae6e8c8d 100644 --- a/docs/userGuide/tipsAndTricks.md +++ b/docs/userGuide/tipsAndTricks.md @@ -9,7 +9,7 @@ # {{ title | safe }} - +
    ##### :fas-lightbulb: Escaping Characters @@ -22,11 +22,11 @@ For Markdown syntax: To display a literal character that are normally used for M * item 1 - + More info: [https://www.markdownguide.org/basic-syntax#escaping-characters](https://www.markdownguide.org/basic-syntax#escaping-characters) - +
    --- @@ -77,7 +77,7 @@ When you use links or triggers, you may encounter a situation where an unwanted --- - +
    ##### :fas-info: Configuring Online Deployment platforms to use specific MarkBind version @@ -120,11 +120,11 @@ Here are the steps to set up Netlify to use a specific version of MarkBind. - +
    --- - +
    ##### :fas-lightbulb: Indent components @@ -169,9 +169,9 @@ to the component. The following examples show how to do this. The following box component will be included via ``. - +
    Some text from include - +
    html @@ -184,5 +184,5 @@ The following box component will be included via ``. -     +
    diff --git a/docs/userGuide/troubleshooting.md b/docs/userGuide/troubleshooting.md new file mode 100644 index 0000000000..1b3924f5aa --- /dev/null +++ b/docs/userGuide/troubleshooting.md @@ -0,0 +1,59 @@ +{% set title = "Troubleshooting" %} +{{ title }} + + + title: "User Guide: {{ title | safe }}" + layout: userGuide.md + pageNav: 5 + + +# {{ title | safe }} + +##### HTML Rendering Issues + +Unexpected behavior can occur in rendered pages due to a number of different reasons. One of these reasons is when the rendered pages are not valid HTML. + +Incorrect HTML markup can be due to: +- nesting block-level elements inside `

    ` or `` elements +- missing `` tags + +###### Example: block-level elements inside `` elements +```html + + + +Animal | Trainable? | Price | Remarks +:------|:----------:|------:|-------- +Ants | no | 5 | +Bees | no | 20 | +Cats | yes | 100 | + +``` + +The table specified by the markdown syntax above will be rendered as a block-level element, which will be included in a inline span element. This makes the HTML output invalid. + + + +``` +vue.js:634 [Vue warn]: The client-side rendered virtual DOM tree is not matching server-rendered content. +This is likely caused by incorrect HTML markup, for example nesting block-level elements inside `

    `, +or missing ``. +Bailing hydration and performing full client-side render. +``` +See [SSR guide for Vue](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch) for more details on hydration mismatch. + + +A possible fix for the above situation is to wrap the table in a `

    ` element instead: + +```html + +
    + +Animal | Trainable? | Price | Remarks +:------|:----------:|------:|-------- +Ants | no | 5 | +Bees | no | 20 | +Cats | yes | 100 | +
    +``` + diff --git a/docs/userGuide/usingComponents.md b/docs/userGuide/usingComponents.md index 18735fdf26..d951195b87 100644 --- a/docs/userGuide/usingComponents.md +++ b/docs/userGuide/usingComponents.md @@ -14,10 +14,10 @@ # Using Components - +
    **MarkBind provides a number of components** (e.g., expandable panels, tabbed displays, navigation bars, etc.) that you can use to enhance the appearance/behavior of your pages. - +
    To use a component, just use the corresponding markup in your file. For example, to create a Panel, you just need to use the markup: diff --git a/docs/userGuide/usingHtmlJavaScriptCss.md b/docs/userGuide/usingHtmlJavaScriptCss.md index 90892b697b..3d67b3e1d8 100644 --- a/docs/userGuide/usingHtmlJavaScriptCss.md +++ b/docs/userGuide/usingHtmlJavaScriptCss.md @@ -13,10 +13,10 @@ # {{ title }} - +
    **A MarkBind source file can contain a mixture of HTML, JavaScript, and CSS** as a normal web page would. - +
    ==Text within HTML tags are considered plain text unless the text is preceded by a blank line,== in which case the text is parsed as Markdown text. @@ -27,14 +27,14 @@ html - +
    Without preceding blank line: Apples **Bananas** Cherries - +
    - +
    With preceding blank line: Apples **Bananas** Cherries - +
         @@ -49,13 +49,13 @@ Alternatively, you can use `` (for _block_ Markdown elements such as h html - +
    Apples **Bananas** Cherries - +
    - +
    ##### Apples **Bananas** Cherries - +