Add text support for icon in unordered lists

Author: yucheng11122017

docs/userGuide/deployingTheSite.md

@@ -20,19 +20,19 @@
 </div>
 
 ## Generic steps for deploying a MarkBind site
-
-1. Set the [`baseUrl` property of the `site.json` file](siteJsonFile.html#baseurl) to match the deploy location.
-1. (Optional) Use the [`markbind serve` command](cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected.
-1. Use the [`markbind build` command](cliCommands.html#build-command) to generate the site from source files. That command puts the generated site files in a directory named `_site` (you can change the output directory using parameters supplied to the command).
-1. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
+* Set the [`baseUrl` property of the `site.json` file](siteJsonFile.html#baseurl) to match the deploy location. { text="Step 1:" }
+* (Optional) Use the [`markbind serve` command](cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected. { text="Step 2:" }
+* Use the [`markbind build` command](cliCommands.html#build-command) to generate the site from source files. That command puts the generated site files in a directory named `_site` (you can change the output directory using parameters supplied to the command). { text="Step 3:" }
+* Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms. { text="Step 4:" }
 
 **Steps for deploying multiple MarkBind sites:**
 
-1. Create multiple `site.json` files. Ensure that the [`baseUrl` property of each `site.json` file](siteJsonFile.html#baseurl) matches its deploy location.
-1. (Optional) Use the [`markbind serve -s <file>` command](cliCommands.html#serve-command) to stage each site locally and confirm the contents are as expected.
-1. For each site:
-    1. Use the [`markbind build -s <file>` command](cliCommands.html#build-command) to generate the site from source files.
-    1. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.
+* Create multiple `site.json` files. { text="Step 1:" }
+  * Ensure that the [`baseUrl` property of each `site.json` file](siteJsonFile.html#baseurl) matches its deploy location. { text="Step 1.1:" }
+* (Optional) Use the [`markbind serve -s <file>` command](cliCommands.html#serve-command) to stage each site locally and confirm the contents are as expected. { text="Step 2:" }
+* For each site: { text="Step 3:" }
+  * Use the [`markbind build -s <file>` command](cliCommands.html#build-command) to generate the site from source files. { text="Step 3.1:" }
+  * Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms. { text="Step 3.2:" }
 
 ## Deploying to GitHub Pages
 

docs/userGuide/syntax/lists.md

@@ -18,31 +18,61 @@
 
 ****Customizing the Unordered list appearance:****
 
-**To customize unordered lists' icons, add the configuration `{icon="icon-name"}` after a specific list item.**
+**To customize unordered lists' icons, add the configuration `{icon="icon-name"}` and/or `{text="text"}` after a specific list item.**
 
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">markdown</variable>
 <variable name="code">
-* Item 1 { icon="glyphicon-education" }
-* Item 2
+* Item 1 { text="Step 1 :+1:" icon="glyphicon-education" }
+* Item 2 { text="Step 2" }
   * Item 2.1 { icon="fas-file-code" }
   * Item 2.2
-* Item 3 { icon="fas-code-branch" }
+* Item 3 { text="Step 3" }
   * Item 3.1 
-* Item 4 { icon="octicon-git-pull-request" }
+* Item 4 { text="\`PR`" icon="octicon-git-pull-request" }
   * Item 4.1 { icon="mif-perm-media" }
-* Item 5 { icon="glyphicon-education" }
+* Item 5 { text="Step 5" icon="glyphicon-education" }
   * Item 5.1 { icon="notebook_with_decorative_cover" }
   </variable>
 </include>
 
+<box type=info seamless>
+
+Customization will be carried over to the other items within the **same level of the list**.
+Example: 
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+* Item 1 { icon="glyphicon-education" }
+  * Item 1.1
+* Item 2 
+  </variable>
+</include>
+
+The customised icon appears for Item 2 but not for Item 1.1.
+
+Hence, if you customize any item on a certain level, you must also **customize the first item on that level**. If not, the list will revert to its uncustomized form.
+If you wish to remove the customization from the following levels, you can set `text` and/or `icon` to be an empty string `""`. 
+
+Example:
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+* Item 1 { icon="glyphicon-education" text="Only for this bullet" }
+* Item 2 { icon="" }
+  </variable>
+  </include>
+</box>
+
 You can use any of the [icons](../formattingContents.html#icons) supported by MarkBind. If an item has a specified icon, that icon will be used for it and for subsequent items at that level.
 
+Markdown can also be used in texts.
+
 <box type=warning seamless>
-If you customize any item on a certain level, you must also customize the first item on that level. If not, the list will revert to its uncustomized form.
+You may need to add escape characters when using special characters for Markdown in text. 
 </box>
 
-**You can adjust the icon's size by using the `i-size` attribute.**
+**You can adjust the icon and text's size by using the `i-size` and `t-size` attribute respectively.**
 
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">markdown</variable>
@@ -55,6 +85,17 @@ If you customize any item on a certain level, you must also customize the first
 </variable>
 </include>
 
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+
+* Item 1 { text="Step 1" t-size="35px" }
+* Item 2 { text="Step 2" t-size="4rem" }
+* Item 3 { text="Step 3" t-size="5em" }
+
+</variable>
+</include>
+
 You can utilize any [CSS size unit](https://www.w3schools.com/cssref/css_units.php).
 
 **You can also use images as icons.**
@@ -72,19 +113,19 @@ You can utilize any [CSS size unit](https://www.w3schools.com/cssref/css_units.p
 
 If either the `i-width` or the `i-height` of an image is not specified, the unspecified dimension will adjust to maintain the image's original aspect ratio. For example, for an image of size 800x600 (4:3), if `i-width` is set to 400px, its height will be 300px.
 
-**The icon's appearance can be further customized by adding a `i-class` attribute.**
+**The icon and text's appearance can be further customized by adding a `i-class` and `t-class` attribute respectively.**
 
 <div id="main-example-markbind">
 
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">markdown</variable>
 <variable name="code">
-* Item 1 { icon="/images/deer.jpg" i-width="60px" height="17px" i-class="rounded" }
-* Item 2
+* Item 1 { icon="/images/deer.jpg" text="Deer" i-width="60px" height="17px" i-class="rounded" t-class="text-warning my-2" }
+* Item 2 { t-class="text-info my-2" }
   * Item 2.1 { icon="fas-question-circle" i-class="badge rounded-pill my-1 bg-success text-white" }
   * Item 2.2
   * Item 2.3 { i-class="badge rounded-pill my-1 bg-primary text-white"}
-* Item 3
+* Item 3 { t-class="text-primary my-2" }
   * Item 3.1 
   * Item 3.2  { icon="fas-question-circle" i-class="badge rounded my-1 bg-danger text-white" }
   * Item 3.3 
@@ -104,9 +145,22 @@ If either the `i-width` or the `i-height` of an image is not specified, the unsp
 
 <box type=tip seamless>
 
-Similar to the `icon` attribute, other icon attributes such as `i-class`, `i-width`, `i-height`, `i-spacing` apply for subsequent list items at the same level, until they are overridden by the same attribute. For example, Item 2.3's `i-class` overrides Item 2.1's and applies up to Item 3.1.
+Similar to the `icon` and `text` attribute, other icon attributes such as `i-class`, `i-width`, `i-height`, `i-spacing`, `t-size` and `t-class` apply for subsequent list items at the same level, until they are overridden by the same attribute. For example, Item 2.3's `i-class` overrides Item 2.1's and applies up to Item 3.1.
+
 </box>
 
+**The spacing between the icon and the content can be customized by using a `i-spacing` attribute.**
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">markdown</variable>
+<variable name="code">
+* Item 1 { icon="+1" text="Yay" }
+* Item 2 { i-spacing="1rem" }
+* Item 3 { i-spacing="2rem" }
+</variable>
+</include>
+
+
 </div>
 
 **You can apply Markdown's heading and paragraph syntax within the list.**