Make cosmetic tweaks to User Docs (#648)

docs/_markbind/boilerplates/tip.md

@@ -0,0 +1,4 @@
+<box border-left-color="{{ markbind_blue }}">
+
+{{ icon_bulb_blue }} {{ tip_body | safe }}
+</box>

docs/index.md

@@ -13,7 +13,7 @@
 
 <big>**Generate dynamic websites from Markdown text.**</big>
 
-MarkBind can use Markdown documents to generate <tooltip content="as opposed to _one-size-fits-all_ static content">_more dynamic_</tooltip> websites that facilitates _<tooltip content="i.e., the reader can chart their own path through the content and consume more/less content as desired">self-directed consumption</tooltip>_. MarkBind is ideal for creating content-heavy instructional websites <br> %%e.g., eLearning websites, online instruction manuals, project documentation etc.%%.
+MarkBind can use Markdown documents to generate <tooltip content="as opposed to _one-size-fits-all_ static content">_more dynamic_</tooltip> websites. MarkBind is ideal for creating text-heavy websites %%e.g., eLearning websites, online instruction manuals, project documentation etc.%%.
 </span>
 
 <b-btn variant="primary" href="{{ baseUrl }}/userGuide/">Get Started</b-btn>
@@ -127,9 +127,9 @@ Details of exercise 3
 
 <hr><!-- ======================================================================================================= -->
 
-#### {{ icon_check_blue }} Everything you need for instructional websites, built-in.
+#### {{ icon_check_blue }} Everything you need for text-heavy websites, built-in.
 
-MarkBind is **highly optimized for creating content-heavy instructional websites** %%e.g., eLearning websites, online instruction manuals, project documentation etc.%% Anything that you might need for creating such websites are built-in, sparing you the hassle of finding/installing/searching plugins that you need.
+MarkBind is **highly optimized for creating text-heavy websites** %%e.g., eLearning websites, online instruction manuals, project documentation etc.%% Anything that you might need for creating such websites are built-in, sparing you the hassle of finding/installing/searching plugins that you need.
 
 Here are some examples:
 <div class="indented">
@@ -145,7 +145,7 @@ Here are some examples:
 
 A MarkBind website can be a _buffet_ of content, as opposed to a _set menu_: a site can have optional contents that the reader can access at her discretion, and the same content can be organized in multiple ways so that the reader can choose the one that fits the need. To _cater_ (pun intended) for creating such buffet style websites, MarkBind has **[reuse mechanisms]({{ baseUrl }}/userGuide/reusingContents.html) for presenting the same content in multiple ways without duplicating the source file**.
 
-For example, MarkBind has a powerful `include` mechanism that allows content fragments (i.e., a file or part of a file) to be reused at multiple places in the website. In the example below, both the modal and the expandable panel reuses the same content originating from a _single_ source file.
+For example, MarkBind has a powerful `include` mechanism that allows content fragments (i.e., a file or part of a file) to be reused at multiple places in the website. In the example below, both the modal and the expandable panel reuse the same content originating from a _single_ source file.
 
 <box>
 

docs/userGuide/addingPages.md

@@ -35,7 +35,7 @@
 Here are the steps to add a new page to your site:
 1. Add a `.md` (or `.mbd`) file anywhere inside the root directory.
 1. Update the [`pages` attribute of the `site.json`]({{ baseUrl }}/userGuide/siteConfiguration.html#pages) to cover the new file, if necessary.
-1. Use the <trigger trigger="click" for="modal:addingPages-livePreview">live preview</trigger> to view the generated web page for the new file. <br> %%If the live preview is running already, you might have to restart it to capture the new file.%%
+1. Use the <trigger trigger="click" for="modal:addingPages-livePreview">live preview</trigger> to view the generated web page for the new file.
 
 <modal large title="Live Preview" id="modal:addingPages-livePreview">
 <include src="glossary.md#live-preview" inline/>

docs/userGuide/gettingStarted.md

@@ -50,11 +50,13 @@ Navigate into an empty directory and run the following command to initialize a s
 $ markbind init
 ```
 
-<box border-left-color="{{ markbind_blue}}">
-
-{{ icon_bulb_blue }} You can add the `--help` flag to any command to show the help screen. <br>
+<include src="tip.md" boilerplate >
+<span id="tip_body">
+You can add the `--help` flag to any command to show the help screen. <br>
   e.g., `markbind init --help`
-</box>
+</span>
+</include>
+
 
   </tab>
   <tab header="Starting with an existing project">

docs/userGuide/markBindSyntax.md

@@ -342,13 +342,13 @@ Links to files of the generated site (e.g., an HTML page or an image file) shoul
 
 MarkBind supports using Font Icons provided by Font Awesome and Glyphicons.
 
-<box border-left-color="{{ markbind_blue}}">
-
-{{ icon_bulb_blue }} The advantage of font icons over emojis is font icons can be _styled_ to fit your needs.e.g.,
+<include src="tip.md" boilerplate >
+<span id="tip_body">
+The advantage of font icons over emojis is font icons can be _styled_ to fit your needs.e.g.,
 * emoji: <font color="purple">Don't judge the :book: by it's cover! :-1:</font>
 * font icons: <font color="purple">Don't judge the {{ fas_book }} by it's cover! {{ icon_dislike }}</font>
-</box>
-
+</span>
+</include>
 
 ###### Using Font Awesome Icons
 1. Decide which icon you want to use from the [list of available icons](https://fontawesome.com/icons?d=gallery&m=free).

docs/userGuide/reusingContents.md

@@ -183,21 +183,6 @@ Tip 3. ...
 ```
 </div>
 
-Attributes:
-* `src`: specify the source file path.
-* `inline` (optional): make the included result an inline element. (wrapped in `<span>` tag). e.g.,
-  ```html
-  <include src="../docs/summary.md" inline />
-   ```
-* `optional` (optional): include the document only if it exists i.e., there will be no error message if the file does not exist. e.g.,
-  ```html
-  <include src="UserStories.md" optional />
-  ```
-* `trim` (optional): remove leading and trailing whitespace and newlines from the document before including.
-  ```html
-  <include src="frament.md" trim />
-  ```
-
 **You can `<include>` 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 `<div>`/`<span>`/`<seg>` tag with the matching `id`.
 
 <div class="indented">
@@ -226,11 +211,26 @@ When setting the `id` of a fragment, be careful not to clash with heading anchor
 
 </box>
 
+**Attributes:**
+* **`src`**: specify the source file path.
+* **`inline`** (optional): make the included result an inline element. (wrapped in `<span>` tag). e.g.,
+  ```html
+  The title is <include src="../docs/summary.md#title" inline /> while ...
+   ```
+* **`optional`** (optional): include the file/fragment only if it exists i.e., there will be no error message if the file/fragment does not exist. e.g.,
+  ```html
+  <include src="UserStories.md" optional />
+  ```
+* **`trim`** (optional): remove leading and trailing whitespace and newlines from the document before including.
+  ```html
+  <include src="UserStories.md#epic" trim />
+  ```
 
-<box border-left-color="{{ markbind_blue}}">
-
-{{ icon_bulb_blue }} The `<include>` tag works for any MarBind source file including the _font matter_ section but it may not work in some _special_ files such as the `_markbind/variables.md`.
-</box>
+<include src="tip.md" boilerplate >
+<span id="tip_body">
+The `<include>` mechanism can be used inside any MarkBind source file (even inside the _front matter_ section) but it will not work inside some _special_ files such as the `_markbind/variables.md`.
+</span>
+</include>
 
 ##### `<include>` Inside an Included File
 
@@ -427,10 +427,12 @@ c:/course/
 ```
 </div>
 
-<box border-left-color="{{ markbind_blue}}">
+<include src="tip.md" boilerplate >
+<span id="tip_body">
+If you are using Git for version control, you can set up the sub-site repository as a [Git sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules) of the main site repository.
+</span>
+</include>
 
-{{ icon_bulb_blue }} If you are using Git for version control, you can set up the sub-site repository as a [Git sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules) of the main site repository.
-</box>
 
 <hr><!-- ======================================================================================================= -->
 

docs/userGuide/tipsTricksAndTroubleshooting.md

@@ -8,7 +8,7 @@
 
 <div class="website-content">
 
-# Troubleshooting
+# Tips, Tricks, & Troubleshooting
 
 ##### Problem: Unwanted starting space in links and triggers