diff --git a/docs/devGuide/projectManagement.md b/docs/devGuide/projectManagement.md index a267057b1f..4e9a4a849d 100644 --- a/docs/devGuide/projectManagement.md +++ b/docs/devGuide/projectManagement.md @@ -98,17 +98,21 @@ For general best practices, refer to the guide [_Working with PRs_ @SE-EDU](http ## Doing a Release - - - -**Attention new maintainers!** Ensure that: - -* You have the rights to push to master branch on [MarkBind's repository](https://github.com/MarkBind/markbind), and also to make new releases. -* You have the rights on [npm](https://www.npmjs.com/) to make a new release. -* You have logged in to npm on your terminal with `npm login` (necessary to publish packages to npm). - - -
+1. **Make sure you have the correct permissions** for [MarkBind's GitHub repository](https://github.com/MarkBind/markbind) and [npm organization](https://www.npmjs.com/org/markbind). + * For GitHub, you need rights to **push to master branch** and **make new releases**. + * To check if you can make a new release and push to master branch, go to the [release page](https://github.com/MarkBind/markbind/releases) and check for the "Draft a new release" button. + If missing, you may not have permissions for a release. + + * For npm, you need to be in the [MarkBind organization](https://www.npmjs.com/org/markbind). + + * To check if you are in the MarkBind organization, go to your npm profile and check if MarkBind is listed under organizations. + + Example of profile that has been added to Markbind organisation + + * There should be 4 packages listed under the organization, `markbind-cli`, `@markbind/core`, `@markbind/core-web` and `@markbind/vue_components`. + * Notably, the first three are packages that we publish every release while the last one has since become a private package consumed internally. + +1. **Login to your npm account in your terminal** by running `npm login`. 1. **Make sure to start with a "clean slate"** by running `npx lerna clean` and then `npm run setup` in the root MarkBind directory. diff --git a/docs/images/npm-profile.jpg b/docs/images/npm-profile.jpg new file mode 100644 index 0000000000..5f7bfd42f0 Binary files /dev/null and b/docs/images/npm-profile.jpg differ diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index ae93315c46..4e7a3a65d0 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -20,19 +20,19 @@ ## 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 ` 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 ` 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 ` 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 ` 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 diff --git a/docs/userGuide/syntax/code.md b/docs/userGuide/syntax/code.md index ad0550ef23..96a01eb264 100644 --- a/docs/userGuide/syntax/code.md +++ b/docs/userGuide/syntax/code.md @@ -281,7 +281,17 @@ A _wrap text_ button can be added to code blocks using the `codeBlockWrapButtons ##### Printing optimization
-Markbind enhances the readability of your code blocks for printing by applying soft wrapping, ensuring code doesn't get cut off. Additionally, line numbers are added to maintain context when wrapping occurs. +Markbind enhances the readability of your code blocks for printing by + +- Applying soft wrapping, ensuring code doesn't get cut off +- Adding line numbers to maintain context when wrapping occurs +- Automatically changing dark code theme to light +- Removing [codeBlockCopyButtons]({{baseUrl}}/userGuide/formattingContents.html#copy-button) and [codeBlockWrapButtons]({{baseUrl}}/userGuide/formattingContents.html#wrap-text-button) + + + There are some issues with printing in Firefox. Please use other browsers such as Chrome if these issues persist. + +

diff --git a/docs/userGuide/syntax/lists.md b/docs/userGuide/syntax/lists.md index 77f863fec1..bcff639133 100644 --- a/docs/userGuide/syntax/lists.md +++ b/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.** markdown -* 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" } + + +Customization will be carried over to the other items within the **same level of the list**. +Example: + +markdown + +* Item 1 { icon="glyphicon-education" } + * Item 1.1 +* Item 2 + + + +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: + +markdown + +* Item 1 { icon="glyphicon-education" text="Only for this bullet" } +* Item 2 { icon="" } + + + + 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. + -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. -**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.** markdown @@ -55,6 +85,17 @@ If you customize any item on a certain level, you must also customize the first + +markdown + + +* Item 1 { text="Step 1" t-size="35px" } +* Item 2 { text="Step 2" t-size="4rem" } +* Item 3 { text="Step 3" t-size="5em" } + + + + 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.**
markdown -* 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 -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. + +**The spacing between the icon and the content can be customized by using a `i-spacing` attribute.** + + +markdown + +* Item 1 { icon="+1" text="Yay" } +* Item 2 { i-spacing="1rem" } +* Item 3 { i-spacing="2rem" } + + + +
**You can apply Markdown's heading and paragraph syntax within the list.** diff --git a/packages/cli/test/functional/test_site/expected/testList.html b/packages/cli/test/functional/test_site/expected/testList.html index 4278834e68..3bbc869e03 100644 --- a/packages/cli/test/functional/test_site/expected/testList.html +++ b/packages/cli/test/functional/test_site/expected/testList.html @@ -213,13 +213,21 @@

Testing Site-Nav
  • Only 1 item
    • +
      +
    1. One item with customization text
      2. +
    +
      +
    • +
      Only 1 item
      +
      • +
    1. One item + nested list
    @@ -231,7 +239,7 @@

    Testing Site-Nav
  • @@ -244,6 +252,20 @@

    Testing Site-Nav +
  • +
    Only 1 item +
      +
    • +
      Only 1 item
      +
      • +
    +
    +
    • +
    1. Basic structure
    @@ -306,19 +328,58 @@

    Testing Site-Nav +
  • +
    Item A
    +
    • +
  • +
    Item B +
      +
    • +
      Sub-item B1
      +
      • +
    • +
      Sub-item B2
      +
      • +
    • +
      Sub-item B3 +
        +
      • +
        Sub-sub-item B3.1
        +
        • +
      • +
        Sub-sub-item B3.2 +
          +
        • Sub-sub-sub-item B3.2.1
          • +
        +
        +
        • +
      +
      +
      • +
    • +
      Sub-item B4
      +
      • +
    +
    +
    • +
    1. First item no customization test