Merge branch 'MarkBind:master' into master

KevinEyo1 · Apr 24, 2024 · 5f722b6 · 5f722b6
2 parents 4bdfdae + f448b73
commit 5f722b6
Show file tree

Hide file tree

Showing 226 changed files with 10,010 additions and 16 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -32,6 +32,8 @@ jobs:
         with:
           java-version: '11'
           distribution: 'temurin'
+      - if: matrix.platform == 'macos-latest'
+        run: brew install python-setuptools
       - run: npm run setup
       - run: npm run test
       - name: Upload coverage report to Codecov
@@ -73,6 +75,8 @@ jobs:
     # disabled on forks
     if: github.event_name == 'push' && github.repository == 'MarkBind/markbind'
     runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
     permissions:
       contents: read
     steps:

diff --git a/docs/devGuide/design/serverSideRendering.md b/docs/devGuide/design/serverSideRendering.md
@@ -102,6 +102,12 @@ Some common mistakes are as such:
 If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
 </box>
 
+<box type="info" seamless>
+Modern browsers have robust inbuilt mechanisms to auto-correct common causes of hydration. Therefore, to avoid high false positive rate, Markbind has a minimalist rule-based validation against violations. The code for this is located in `core/src/utils/htmlValidationUtils.ts`. 
+
+Please help extend it when violations that cause hydration on browsers are spotted.
+</box>
+
 Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).
 
 {% from "njk/common.njk" import previous_next %}

diff --git a/docs/site.json b/docs/site.json
@@ -25,7 +25,9 @@
     "mathDelimiters",
     "codeBlockWrapButtons",
     "web3Form",
-    "codeBlockCopyButtons"
+    "codeBlockCopyButtons",
+    "dataTable",
+    "mermaid"
   ],
   "pluginsContext" : {
     "filterTags" : {

diff --git a/docs/userGuide/plugins/dataTable.md b/docs/userGuide/plugins/dataTable.md
@@ -0,0 +1,66 @@
+### Plugin: DataTable
+
+The [DataTable](https://datatables.net) plugin enhances the functionality of tables in your MarkBind site by integrating the DataTables library. It allows you to add searching and sorting capabilities to your tables with minimal configuration. The necessary CSS and JavaScript files are already included in the project, so no additional CDN or plugin context configuration is required.
+
+To enable this plugin, simply add `dataTable` to your site's plugins:
+
+```js {heading="site.json"}
+{
+  ...
+  "plugins": [
+    "dataTable"
+  ]
+}
+```
+
+To create a table with DataTable features, use one of the following syntaxes:
+
+{{ icon_example }} Sortable Table:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<d-table sortable>
+| Product   | Price | Quantity |
+|-----------|-------|----------|
+| Apple     | $0.50 | 100      |
+| Banana    | $0.75 | 50       |
+| Orange    | $0.60 | 75       |
+</d-table>
+</variable>
+</include>
+
+{{ icon_example }} Searchable Table:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<d-table searchable>
+| Book Title                | Author           | Year Published |
+|---------------------------|------------------|----------------|
+| To Kill a Mockingbird     | Harper Lee       | 1960           |
+| 1984                      | George Orwell    | 1949           |
+| Pride and Prejudice       | Jane Austen      | 1813           |
+| The Great Gatsby          | F. Scott Fitzgerald | 1925        |
+</d-table>
+</variable>
+</include>
+
+{{ icon_example }} Sortable and Searchable Table:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<d-table sortable searchable>
+| City        | Country   | Population |
+|-------------|-----------|------------|
+| New York    | USA       | 8,336,817  |
+| London      | UK        | 9,002,488  |
+| Paris       | France    | 2,161,063  |
+| Tokyo       | Japan     | 13,960,236 |
+| Sydney      | Australia | 5,367,206  |
+</d-table>
+</variable>
+</include>
+
+The DataTable plugin automatically renders the table with the specified features based on the presence of the `sortable` and `searchable` attributes in the `<d-table>` tag. You can use either one or both attributes to control the desired functionality for each table.
diff --git a/docs/userGuide/plugins/mermaid.md b/docs/userGuide/plugins/mermaid.md
@@ -0,0 +1,112 @@
+### Plugin: Mermaid
+
+<div id="content">
+
+This plugin allows you to utilize [Mermaid](https://mermaid-js.github.io/mermaid/) by automatically importing the library and initializing the rendering of the diagrams.
+
+> Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
+
+<box type="info">
+
+All supported diagrams are available in [the Mermaid official documentation](https://mermaid-js.github.io/mermaid/).
+
+</box>
+
+To enable this plugin, add `mermaid` to your site's plugins.
+
+```js {heading="site.json"}
+{
+  ...
+  "plugins": [
+    "mermaid"
+  ]
+}
+```
+
+<panel header="Optional: Specify an alternative URL to load the Mermaid code">
+
+By default, the plugin loads the Mermaid code from a CDN URL. However, you can optionally specify an alternative URL to load the Mermaid code from a different source.
+
+```js {heading="site.json"}
+{
+  ...
+  "plugins": [
+    "mermaid"
+  ],
+  "pluginsContext": {
+    "mermaid": {
+      "address": "https://unpkg.com/mermaid@10/dist/mermaid.esm.min.mjs" // replace with URL of your choice
+    }
+  }
+}
+```
+
+</panel>
+
+To create a Mermaid diagram, use the `<mermaid>` tag and provide the diagram definition within the tag.
+
+{{ icon_example }} Pie Chart:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<mermaid>
+pie title Pets adopted by volunteers
+    "Dogs" : 386
+    "Cats" : 85
+    "Rats" : 15
+</mermaid>
+</variable>
+</include>
+
+{{ icon_example }} Flowchart:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<mermaid>
+flowchart TD
+    A[Start] --> B{Is it?}
+    B -->|Yes| C[OK]
+    C --> D[Rethink]
+    D --> B
+    B ---->|No| E[End]
+</mermaid>
+</variable>
+</include>
+
+{{ icon_example }} User Journey Diagram:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<mermaid>
+journey
+    title My working day
+    section Go to work
+      Make tea: 5: Me
+      Go upstairs: 3: Me
+      Do work: 1: Me, Cat
+</mermaid>
+</variable>
+</include>
+
+{{ icon_example }} Gitgraph Diagram:
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<mermaid>
+gitGraph
+    commit
+    branch develop
+    checkout develop
+    commit
+    checkout main
+    merge develop
+</mermaid>
+</variable>
+</include>
+
+The plugin automatically converts the `<mermaid>` tags into appropriate `<div>` elements with the necessary classes and attributes for rendering the diagrams using the Mermaid library.
+<div>
diff --git a/docs/userGuide/syntax/diagrams.md b/docs/userGuide/syntax/diagrams.md
@@ -1,5 +1,6 @@
 ## Diagrams
 
+### PlantUML Diagrams
 You can use the [PlantUML](http://plantuml.com/) syntax to add diagrams.
 
 <box type="warning">
@@ -159,3 +160,7 @@ bob -> bob ++ : self call
 <include src="diagrams.md#puml-examples" />
 
 </div>
+
+### Mermaid Diagrams
+
+<include src="{{ baseUrl }}/userGuide/plugins/mermaid.md#content" />
diff --git a/docs/userGuide/syntax/includes.md b/docs/userGuide/syntax/includes.md
@@ -52,10 +52,34 @@ Tip 2. ...
 <box type="warning">
 
 When setting the `id` of a fragment, be careful not to clash with heading anchor IDs auto-generated by MarkBind. For example, if you have a heading `## Some Useful Tips`, MarkBind will auto-generate an ID `some-useful-tips` for that heading.
+</box>
+<include src="panels.md#script_and_styles_warning"></include>
+<div id="baseUrl-warning">
+<box type="warning" header="Add `{{ '{{ baseUrl }}' }}` to make your URLs absolute links if they may be reused in different contexts">
+
+Make an internal relative link an absolute link by adding `{{ '{{ baseUrl }}' }}` in front of the path. This allows the link to always point to the same target. Keep this in mind when putting content with links that is reused (eg: via `<include>`). This is because when your content is re-used, a relative link may no longer point to where you want it to.
+<div id="baseUrl-example">
+<panel header="Example of using absolute links in `<include>`">
+
+The file `folder1/file1.md` contains a link to `folder1/target.html`. The file `folder2/file2.md` contains `folder1/file1.md` using `<include>`.
+
+**In `folder2/file2.md`:** 
+```
+<include src="folder1/file1.md" />
+```
+<box type="success" header="Positive example">
 
+To ensure that the link will still point to `folder1/target.html`, use an **absolute link** in `folder1/file1.md` as such: `{{ '{{baseUrl}}' }}/folder1/target.html`.
 </box>
+<box type="wrong" header="Negative example">
 
-<include src="panels.md#script_and_styles_warning"></include>
+If a relative link `target.html` is used, the link in `folder2/file2.md` will point to `folder2/target.html` instead of `folder1/target.html`
+</box>
+</panel>
+<br/>
+</div>
+</box>
+</div>
 
 <include src="tip.md" boilerplate >
 <span id="tip_body">

diff --git a/docs/userGuide/syntax/lists.md b/docs/userGuide/syntax/lists.md
@@ -36,6 +36,45 @@
   </variable>
 </include>
 
+**You can also use `{texts="['text1', 'text2', 'text3']"}` syntax to add text customisation to a level quickly**
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+* Item 1 { texts="['(a)','(b)','(c)','(d)']" }
+  * sub level not applied as per norm
+* Item 2
+* You can override once like this { text="OverrideOnce" once=true }
+* Item 3
+* Item 4
+* Last text config will be applied when the list length exceeds texts
+* Another last text
+* You can override like this { text="OVERRIDE" }
+* Another overrided text
+  </variable>
+</include>
+
+<box type=warning seamless>
+
+Please be alerted that when using the `{texts="['text1', 'text2', 'text3']"}` syntax, you need to have`""` outside the array, and use `''` for the string inside the array.
+
+<panel header="Notes on having single quote `'` inside text"  minimized>
+
+If you want to use `'` in you text icon, you need to escape it with double escape sequence. 
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+1. Text-icons of lists can use double escape to include quote test
+* item 1 { texts="['\\'a\\'','\\'b\\'','\\'c\\'']" }
+* item 1
+* item 1
+  </variable>
+</include>
+</panel>
+</box>
+
+
+
 <box type=info seamless>
 
 Customization will be carried over to the other items within the **same level of the list**.

diff --git a/docs/userGuide/syntax/panels.md b/docs/userGuide/syntax/panels.md
@@ -104,6 +104,14 @@ plain text ...
 </variable>
 </include>
 
+<box background-color="#C51E3A" color="white">
+
+  :bulb: Seamless panels inherit the background colour and text colour of any parents!
+  <br/>
+  <panel type="seamless" header="This is an example seamless panel">
+    This is its content.
+  </panel>
+</box>
 
 **Show/Hide buttons using `no-switch`, `no-close`, or `no-minimized-switch`.**
 
@@ -167,6 +175,8 @@ To safeguard against unintended consequences, consider directly incorporating th
 </variable>
 </include>
 
+<include src="includes.md#baseUrl-warning"/>
+
 **If `preload` attribute is provided, the panel body will load the HTML when the page renders instead of after being expanded.**
 
 <include src="codeAndOutput.md" boilerplate >

diff --git a/docs/userGuide/syntax/popovers.md b/docs/userGuide/syntax/popovers.md
@@ -71,6 +71,8 @@
 </variable>
 </include>
 
+<include src="includes.md#baseUrl-warning"/>
+
 **Using trigger for Popover:**<br>
 
 <include src="codeAndOutput.md" boilerplate >

diff --git a/docs/userGuide/syntax/siteNavigationMenus.md b/docs/userGuide/syntax/siteNavigationMenus.md
@@ -34,7 +34,10 @@ You can **append the `:expanded:` to a <tooltip content="a menu item with sub me
 
 </div>
 
-<div id="examples"></div>
+<div id="examples" class="d-none">
+
+You can see an example of a Site Navigation Menu ==on the left side== of <a target="_blank" href="{{ baseUrl }}/userGuide/formattingContents.html">this page</a>.
+</div>
 
 <div id="short" class="d-none">
 

diff --git a/docs/userGuide/troubleshooting.md b/docs/userGuide/troubleshooting.md
@@ -93,4 +93,13 @@ You could signpost Markdown either by:
 <box> **This will be rendered as plain text**</box>
 </variable>
 </include>
-</panel>
+</panel>
+
+##### Content with local links not working when included with `<include>`
+
+If you notice that relative links in a page pointing to another page no longer works after adding it into a page via `<include>`, it may be because the relative link no longer points to the correct address in the new page with `<include>`. 
+
+To solve this, change the relative URL into an **absolute** URL by adding `{{ '{{ baseUrl }}' }}`. This will ensure that the link will always point to the same address regardless of the page it is included in.
+
+<include src="syntax/includes.md#baseUrl-example"/>
+
diff --git a/docs/userGuide/usingPlugins.md b/docs/userGuide/usingPlugins.md
@@ -64,6 +64,8 @@ MarkBind has a set of built-in plugins that can be used immediately without inst
 <include src="plugins/disqus.md" />
 <include src="plugins/mathDelimiters.md" />
 <include src="plugins/web3Form.md" />
+<include src="plugins/dataTable.md" />
+<include src="plugins/mermaid.md" />
 
 ## Using External Plugins
 

diff --git a/packages/cli/test/functional/testSites.js b/packages/cli/test/functional/testSites.js
@@ -2,6 +2,7 @@ const testSites = [
   'test_site',
   'test_site_algolia_plugin',
   'test_site_special_tags',
+  'test_site_table_plugin',
 ];
 
 const testConvertSites = [