Combining syntax cheat sheet and full syntax reference pages (#2426)

jingting1412 · web-flow · commit a44bdaa163ab · 2024-03-04T09:27:16.000+08:00
diff --git a/docs/_markbind/layouts/userGuide.md b/docs/_markbind/layouts/userGuide.md
@@ -39,8 +39,7 @@
 * References :expanded:
   * [CLI Commands]({{baseUrl}}/userGuide/cliCommands.html)
   * [Reader-Facing Features]({{baseUrl}}/userGuide/readerFacingFeatures.html)
-  * [Full Syntax Reference]({{baseUrl}}/userGuide/fullSyntaxReference.html)
-  * [Syntax Cheat Sheet]({{baseUrl}}/userGuide/syntaxCheatSheet.html)
+  * [Syntax Reference]({{baseUrl}}/userGuide/syntaxReference.html)
   * [`site.json` File]({{baseUrl}}/userGuide/siteJsonFile.html)
   * [`.gitignore` File]({{baseUrl}}/userGuide/gitignoreFile.html)
   * [Tips & Tricks]({{baseUrl}}/userGuide/tipsAndTricks.html)
diff --git a/docs/site.json b/docs/site.json
@@ -13,8 +13,7 @@
       "src": [
         "index.md",
         "userGuide/index.md",
-        "userGuide/fullSyntaxReference.md",
-        "userGuide/syntaxCheatSheet.md",
+        "userGuide/syntaxReference.md",
         "userGuide/readerFacingFeatures.md",
         "devGuide/index.md"
       ],
diff --git a/docs/ug-site.json b/docs/ug-site.json
@@ -12,8 +12,7 @@
       "src": [
         "index.md",
         "userGuide/index.md",
-        "userGuide/fullSyntaxReference.md",
-        "userGuide/syntaxCheatSheet.md",
+        "userGuide/syntaxReference.md",
         "userGuide/readerFacingFeatures.md"
       ],
       "searchable": "no"
diff --git a/docs/userGuide/components/imagesAndDiagrams.md b/docs/userGuide/components/imagesAndDiagrams.md
@@ -22,15 +22,15 @@ The image components here provide **convenient syntax & styling abstractions** o
 Diagrams, in the form of **inline PlantUML components** are also supported.
 </div>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="../syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-{% if 'images-diagrams' in v[1] %}
+{% if 'images-diagrams' in v[2] %}
 {{ show_topic(k) }}
 {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/components/navigation.md b/docs/userGuide/components/navigation.md
@@ -21,15 +21,15 @@
 The components in this page are used for scaffolding **site and page navigation**.
 </div>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="../syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-{% if 'navigation' in v[1] %}
+{% if 'navigation' in v[2] %}
 {{ show_topic(k) }}
 {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/components/others.md b/docs/userGuide/components/others.md
@@ -21,15 +21,15 @@
 This page lists some other components that may be useful in creating education websites. For now, there are only question and quiz components.
 </div>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="../syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-{% if 'others' in v[1] %}
+{% if 'others' in v[2] %}
 {{ show_topic(k) }}
 {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/components/popups.md b/docs/userGuide/components/popups.md
@@ -21,15 +21,15 @@
 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.
 </div>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="../syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-{% if 'popups' in v[1] %}
+{% if 'popups' in v[2] %}
 {{ show_topic(k) }}
 {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/components/presentation.md b/docs/userGuide/components/presentation.md
@@ -30,15 +30,15 @@ More specifically, you should use either:
 For more information, please refer to this [section]({{baseUrl}}/userGuide/usingHtmlJavaScriptCss.html#markdown-in-html).
 </box>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="../syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-{% if 'presentation' in v[1] %}
+{% if 'presentation' in v[2] %}
 {{ show_topic(k) }}
 {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md
@@ -20,15 +20,15 @@
 
 </div>
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename) %}
 <include src="./syntax/{{ filename }}.md" />
 <hr>
 {% endmacro %}
 
 {% for k,v in topics %}
-  {% if 'basic' in v[1] %}
+  {% if 'basic' in v[2] %}
 {{ show_topic(k) }}
   {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/fullSyntaxReference.md b/docs/userGuide/fullSyntaxReference.md
diff --git a/docs/userGuide/readerFacingFeatures.md b/docs/userGuide/readerFacingFeatures.md
@@ -7,9 +7,8 @@
 
 # Reader-Facing Features
 
-<include src="fullSyntaxReference.md#dummy" optional />
 
-{% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
+{% from "userGuide/syntax/fullSyntaxSet.njk" import syntax_topics as topics %}
 
 {% macro show_topic(filename, heading) %}
 
@@ -26,7 +25,7 @@
 {% endmacro %}
 
 {% for k,v in topics %}
-  {% if 'reader-facing' in v[1] %}
+  {% if 'reader-facing' in v[2] %}
 {{ show_topic( k, v[0]) }}
   {% endif %}
 {% endfor %}
diff --git a/docs/userGuide/syntax/dates.md b/docs/userGuide/syntax/dates.md
@@ -99,8 +99,6 @@ Thu 22/08
 <div id="short" class="d-none">
 
 <box><span>
-{{ njcode('"2019-08-12" | date("DD.MM.YYYY", 10)') }} <!-- 22.08.2019 --><br/>
+{{ njcode('baseDate | date(format, daysToAdd)') }} <!-- 22.08.2019 --><br/>
 </span></box>
-
-{{ "2019-08-12" | date("DD.MM.YYYY", 10) }}
 </div>
diff --git a/docs/userGuide/syntax/fullSyntaxSet.njk b/docs/userGuide/syntax/fullSyntaxSet.njk
@@ -0,0 +1,71 @@
+{% set syntax_topics = {
+  headings : ['Headings', 'headings', ['basic', 'reader-facing']],
+  paragraphs : ['Paragraphs', 'paragraphs', ['basic']],
+  lineBreaks : ['Line Breaks', 'line-breaks', ['basic']],
+  textStyles : ['Text Styles', 'text-styles', ['basic', 'reader-facing']],
+  blockquotes: ['Blockquotes', 'blockquotes', ['basic', 'reader-facing']],
+  lists : ['Lists', 'lists', ['basic', 'reader-facing']],
+  code : ['Code', 'code', ['basic', 'reader-facing']],
+  horizontalrules : ['Horizontal Rules', 'horizontal-rules', ['basic', 'reader-facing']],
+  links : ['Links', 'links', ['basic', 'reader-facing']],
+  footnotes: ['Footnotes', 'footnotes', ['basic', 'reader-facing']],
+  images : ['Images', 'images', ['basic', 'reader-facing']],
+  attributes: ['Classes, Attributes & Identifiers', 'classes-attributes-and-amp-identifiers', ['basic', 'reader-facing']],
+  tables : ['Tables', 'tables', ['basic', 'reader-facing']],
+  emoji : ['Emoji', 'emoji', ['basic', 'reader-facing']],
+  icons : ['Icons', 'icons', ['basic', 'reader-facing']],
+  embeds : ['Embeds', 'embeds', ['basic', 'reader-facing']],
+  dates : ['Dates', 'dates', ['basic', 'reader-facing']],
+  mathformulae : ['Math Formulae', 'math-formulae', ['basic', 'reader-facing']],
+
+  frontmatter : ['Frontmatter', 'frontmatter', ['tweakingThePageStructure']],
+  tags : ['Tags', 'plugin-tags', ['tweakingThePageStructure']],
+  includes : ['Includes', 'includes', ['reusingContents']],
+  variables : ['Variables', 'variables', ['reusingContents']],
+  keywords : ['Keywords', 'keywords', ['makingTheSiteSearchable']],
+
+  badges : ['Badges', 'badges', ['presentation', 'reader-facing']],
+  boxes : ['Boxes', 'boxes', ['presentation', 'reader-facing']],
+  panels : ['Panels', 'panels', ['presentation', 'reader-facing']],
+  tabs : ['Tabs', 'tabs', ['presentation', 'reader-facing']],
+  pictures : ['Pictures', 'pictures', ['images-diagrams', 'reader-facing']],
+  annotations : ['Annotations', 'annotations', ['images-diagrams', 'reader-facing']],
+  thumbnails : ['Thumbnails', 'thumbnails', ['images-diagrams', 'reader-facing']],
+  diagrams : ['Diagrams', 'diagrams', ['images-diagrams', 'reader-facing']],
+  tree : ['Tree', 'tree', ['images-diagrams', 'reader-facing']],
+  tooltips : ['Tooltips', 'tooltips', ['popups', 'reader-facing']],
+  popovers : ['Popovers', 'popovers', ['popups', 'reader-facing']],
+  modals : ['Modals', 'modals', ['popups', 'reader-facing']],
+  dropdowns : ['Dropdowns', 'dropdowns', ['navigation', 'reader-facing']],
+  searchBars : ['Search Bars', 'search-bars', ['navigation', 'reader-facing']],
+  navBars : ['Nav Bars', 'navbars', ['navigation', 'reader-facing']],
+  breadcrumbs : ['Breadcrumbs', 'breadcrumbs', ['navigation', 'reader-facing']],
+  siteNavigationMenus : ['Site Navigation Menus', 'site-navigation-menus', ['navigation', 'reader-facing']],
+  pageNavigationMenus : ['Page Navigation Menus', 'page-navigation-menus', ['navigation', 'reader-facing']],
+  scrollTopButton : ['Scroll To Top Button', 'scroll-to-top-button', ['navigation', 'reader-facing']],
+  questions : ['Questions and Quizzes', 'questions-and-quizzes', ['others', 'reader-facing']]
+} %}
+
+{% macro generate_url(k, v) %}
+  {% set url="/userGuide/" %}
+  {% if v[2] is iterable %}
+    {% if 'basic' in v[2] %}
+      {% set url = url + "formattingContents.html#" + v[1] %}
+    {% elif 'presentation' in v[2] %}
+      {% set url = url + "components/presentation.html#" + v[1] %}
+    {% elif 'images-diagrams' in v[2] %}
+      {% set url = url + "components/imagesAndDiagrams.html#" + v[1] %}
+    {% elif 'popups' in v[2] %}
+      {% set url = url + "components/popups.html#" + v[1] %}
+    {% elif 'navigation' in v[2] %}
+      {% set url = url + "components/navigation.html#" + v[1] %}
+    {% elif 'others' in v[2] %}
+      {% set url = url + "components/others.html#" + v[1] %}
+    {% else %}
+      {% set url = url + v[2][0] + v[1] %}
+    {% endif %}
+  {% else %}
+    {% set url = url %}
+  {% endif%}
+  {{ url }}
+{% endmacro %} 
diff --git a/docs/userGuide/syntax/pageNavigationMenus.md b/docs/userGuide/syntax/pageNavigationMenus.md
@@ -35,6 +35,8 @@ You can specify multiple `<page-nav-print />` components in a page and they do n
 {{ icon_example }}
 In the page that you want to have page navigation printed (i.e. to serve as a table of content when viewed on PDFs), use the `<page-nav-print />` component to position the pageNav like so:
 
+<div id="short" class="indented">
+
 ```html
 <frontmatter>
   pageNav: 2
@@ -47,6 +49,8 @@ In the page that you want to have page navigation printed (i.e. to serve as a ta
 Content of the page...
 ```
 
+</div>
+
 To view the pageNav on print, open the print preview of the page using the browser's print function.
 
 <box type="info" seamless>
@@ -57,32 +61,6 @@ You can try it out by going to our [CLI Commands page]({{baseUrl}}/userGuide/cli
 
 </panel>
 
-<div id="short" class="indented">
-
-{{ icon_example }}
-In the page that you want to have page navigation, you may show only `<h1>` and `<h2>` headings in the pageNav, and set a custom pageNav title like so:
-
-```html
-<frontmatter>
-  pageNav: 2
-  pageNavTitle: "Chapters of This Page"
-</frontmatter>
-```
-
-Then, in your [layout file]({{baseUrl}}/userGuide/tweakingThePageStructure.html#layouts), use the `<page-nav />` component to position the pageNav.
-
-{% if not doNotShowPageNav %}
-{{ icon_example }} <trigger for="modal:page-nav-example" trigger="click">Example usage of the `<page-nav />` component</trigger>
-
-<modal header="Using the `pageNav` variable in a layout" id="modal:page-nav-example" large>
-<include src="../tweakingThePageStructure.md#layout-code-snippet">
-<variable name="highlightLines">54</variable>
-</include>
-</modal>
-{% endif %}
-
-</div>
-
 </div>
 
 <div id="examples" class="d-none">
diff --git a/docs/userGuide/syntax/siteNavigationMenus.md b/docs/userGuide/syntax/siteNavigationMenus.md
@@ -9,7 +9,6 @@ Steps to add a siteNav:
 2. Include it under a `<site-nav>` element.
 3. (Optional) To make siteNav accessible on smaller screens, you can use the `<site-nav-button />` component in the [navbar]({{baseUrl}}/userGuide/components/navigation.html#navbars).
 
-<div id="short">
 
 <include src="codeAndOutput.md" boilerplate >
 <variable name="code">
@@ -25,7 +24,6 @@ Steps to add a siteNav:
 </variable>
 </include>
 
-</div>
 
 MarkBind has styles nested lists with additional padding and smaller text sizes up to **4** nesting levels.
 Beyond that, you'd have to include your own styles.
@@ -37,3 +35,19 @@ You can **append the `:expanded:` to a <tooltip content="a menu item with sub me
 </div>
 
 <div id="examples"></div>
+
+<div id="short" class="d-none">
+
+```html
+<site-nav>
+* [**Getting Started**]({{baseUrl}}/userGuide/gettingStarted.html)
+* **Authoring Contents** :expanded:
+  * [Overview]({{baseUrl}}/userGuide/authoringContents.html)
+  * [Adding Pages]({{baseUrl}}/userGuide/addingPages.html)
+  * [MarkBind Syntax Overview]({{baseUrl}}/userGuide/markBindSyntaxOverview.html)
+  * [Formatting Contents]({{baseUrl}}/userGuide/formattingContents.html)
+  * [Using Components]({{baseUrl}}/userGuide/usingComponents.html)
+</site-nav>
+```
+
+</div>
diff --git a/docs/userGuide/syntax/variables.md b/docs/userGuide/syntax/variables.md
diff --git a/docs/userGuide/syntaxCheatSheet.md b/docs/userGuide/syntaxCheatSheet.md
diff --git a/docs/userGuide/syntaxReference.md b/docs/userGuide/syntaxReference.md
diff --git a/docs/userGuide/usingComponents.md b/docs/userGuide/usingComponents.md
