Restructure user docs #518

damithc · 2019-01-01T09:47:26Z

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update

What is the rationale for this request?
Restructured and revised the documentation as its structure has deteriorated as a natural consequence of piece-meal updates over a long period. I couldn't go as far as I wanted to due to lack of time; this version took the good part of a week :-p

Apologies for mutilating some of the content you wrote beyond recognition. In most cases, I started with the existing content but after numerous refactoring and revising, most are not traceable to the original content anymore.

Also apologies for pushing as one commit. The actual commit history was too chaotic to make any sense.

Finally, apologies to those with ongoing PRs as most likely this PR is going to conflict with doc updates in your PR.

Is there anything you'd like reviewers to focus on?

Read from the perspective of a prospective user. Also look out for factual errors.

Testing instructions:

Use the netlify preview.

yamgent

Thanks for the revamp Prof. :P

Some comments for the first pass:

yamgent · 2019-01-02T06:40:54Z

docs/userGuide/siteConfiguration.md

  "pages": [
    {
      "src": "index.md",
      "title": "Hello World",
+      "layout": "normal"


Missing comma at the end of this line

yamgent · 2019-01-02T06:41:55Z

docs/userGuide/siteConfiguration.md

+
+#### **`titlePrefix`**
+
+The prefix for all page titles. The separator <code>-</code> will be inserted by MarkBind. |


Remove the | at the end.

Also since everything else bolds the first statement, perhaps we can also bold The prefix for all page titles.?

yamgent · 2019-01-02T06:45:27Z

docs/userGuide/siteConfiguration.md

+* **`src`**/**`glob`**: `src` can be used to specify a file e.g., `docs/index.md`.<br>
+    Alternatively, `glob` can be used to define a file pattern in the [_glob syntax_](https://en.wikipedia.org/wiki/Glob_(programming)) e.g., `**/*.md`.
+* **`title`**: The page `<title>` for the generated web page. Titles specified here take priority over titles specified in the [front matter](addingPages.html#front-matter) of individual pages.
+* `layout`: The [layout]({{ baseUrl }}/userGuide/advancedTopics.html#page-layout) to be used by the page.


If the user does not specify the parameter, the default layout is default.

Also, except for src and glob, the rest of the attributes are optional, so perhaps can be marked [optional]?

yamgent · 2019-01-02T06:58:35Z

docs/userGuide/deployingTheSite.md

+
+Generic steps for deploying a MarkBind site:
+1. Set the [`baseUrl` property of the `site.json` file]({{ baseUrl }}/userGuide/siteConfiguration.html#baseUrl) to match the deploy location.
+1. Optionally, use the [`markbind serve` command]({{ baseUrl }}/userGuide/cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected.


I think using (optional) would be clearer than Optionally, ...

yamgent · 2019-01-02T07:02:59Z

docs/userGuide/markBindSyntax.md

+
+## Support for GFMD
+
+**MarkBind supports additional Markdown features provided by Github-Flavored Markdown (GFMD).** A summary is given below. Refer [Github's GFMD documentation](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) for more details.


Refer to Github...

yamgent · 2019-01-02T07:07:26Z

docs/userGuide/markBindSyntax.md

+
+## Support for Nunjucks
+
+[Nunjucks](https://mozilla.github.io/nunjucks/) is a JavaScrip based templating tool. Here is a simple example:


yamgent · 2019-01-02T07:19:18Z

docs/userGuide/reusingContents.md

+Represents the root directory of the project. Used for specifying intra-site links.
+
+<panel type="seamless" header="User Guide: MarkBind Syntax → Intra-Site Links">
+  <include src="markbindSyntax.md#intra-site-links" />


This did not render correctly. The ID should be changed to intraSiteLinks both in here and in markbindSyntax.md

yamgent · 2019-01-02T07:25:40Z

docs/userGuide/reusingContents.md

+
+```markdown
+# My Review
+<include src="../book-files/book.md" />


bookFiles

yamgent · 2019-01-02T07:25:49Z

docs/userGuide/reusingContents.md

+...
+```
+
+The content of the `chapter1.md` and `chapter2.md` will be included in the `review.md` (via `<include src="../book-files/book.md" />`) although `chapter1.md` and `chapter2.md` are not in `reviewFiles` directory. i.e., `<include src="chapter1.md" />` will be interpreted as `<include src="c:/mySite/bookFiles/chapter1.md" />`


bookFiles

Chng-Zhi-Xuan · 2019-01-02T07:32:57Z

Thanks for the initial review @yamgent, will review in the next hour or so.

Chng-Zhi-Xuan · 2019-01-02T09:43:29Z

docs/index.md


-## <span class="glyphicon glyphicon-th-list" aria-hidden="true"></span> Features
+MarkBind can use Markdown documents to generate a <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 %%e.g., eLearning websites, online instruction manuals, project documentation etc.%%.


Add a <br> before 'e.g., eLearning .....' so the greyed text is all on 1 line.

Chng-Zhi-Xuan · 2019-01-02T10:03:07Z

docs/userGuide/gettingStarted.md

+
+<div class="indented">
+
+  %%{{ icon_ticked }}%% a basic knowledge of Markdown and HTML syntax<br>


Maybe link some Markdown / HTML syntax guides if users want to learn?

Markdown

HTML

Chng-Zhi-Xuan · 2019-01-02T10:06:10Z

docs/userGuide/addingPages.md

+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. %%If the live preview is running already, you might have to restart it to capture the new file.%%


<br> before grey text.

Chng-Zhi-Xuan · 2019-01-02T10:19:45Z

docs/userGuide/markBindSyntax.md

+
+#### Icons Fonts
+
+<small>%%Acknowledgement: Font Awesome icons are provided by [Font Awesome](https://fontawesome.com/) under their [free license](https://fontawesome.com/license) while Glyphicons are provided by [Glyphicons](https://glyphicons.com/) via Bootstrap 3.%%</small>


Link to Bootstrap or Bootstrap 3

Chng-Zhi-Xuan · 2019-01-02T10:32:06Z

docs/userGuide/components/panel.md

@@ -99,31 +99,31 @@
 <i style="font-style: normal; font-weight: bold; color: dimgray">Markup</i>

 ```html
-<panel header="#### light type panel (DEFAULT)" type="light" minimized>
+<panel header="###### light type panel (DEFAULT)" type="light" minimized>


Change to follow rendered panel example. Same for the rest of the markup code.

<panel header="**light type panel (DEFAULT)**" type="light" minimized>

yamgent · 2019-01-02T12:13:51Z

There are some recently approved PRs that has new addition to the documentation, and I think it would be better if those PRs actually adapt the new documentation format first before they get merged (rather than having it the other way round, which is this PR having to deal with the new additions).

We can merge this PR first even if there are some substantial flaws, and touch up in a subsequent PR?

Chng-Zhi-Xuan · 2019-01-02T12:41:50Z

@yamgent Good point, I was already thinking where to put page navigation in the refreshed docs as I was reviewing it 😅. Yes, we should prioritise merging this PR first.

damithc · 2019-01-02T12:51:40Z

We can merge this PR first even if there are some substantial flaws, and touch up in a subsequent PR?

Yup, that makes sense. Anything I need to do?

yamgent · 2019-01-03T02:35:00Z

Anything I need to do?

Not atm, the subsequent PR can be carried out by anyone available actually.

acjh · 2019-01-16T05:50:20Z

docs/common/header.md

+  <li><a href="{{baseUrl}}/index.html" class="nav-link">HOME</a></li>
+  <li><a href="{{baseUrl}}/userGuide/index.html" class="nav-link">DOCS</a></li>
+  <li><a href="{{baseUrl}}/showcase.html" class="nav-link">SHOWCASE</a></li>
+  <li><a href="{{baseUrl}}/about.html" class="nav-link">ABOUT</a></li>


@damithc @yamgent It seems the removed dropdown means we can no longer navigate to those pages on mobile.

That is indeed a problem. Ideally, the SiteNav should automatically transform into a drop-down menu. What do you guys think?

Created #591.

Restructure user documents to increase readability

a81886c

yamgent self-requested a review January 2, 2019 06:37

yamgent reviewed Jan 2, 2019

View reviewed changes

yamgent requested a review from Chng-Zhi-Xuan January 2, 2019 07:28

Chng-Zhi-Xuan reviewed Jan 2, 2019

View reviewed changes

yamgent merged commit ce1677a into MarkBind:master Jan 3, 2019

yamgent added this to the v1.15.3 milestone Jan 3, 2019

damithc mentioned this pull request Jan 3, 2019

Apply a default layout for the MarkBind website #527

Closed

acjh reviewed Jan 16, 2019

View reviewed changes

yamgent mentioned this pull request Jan 17, 2019

siteNav: Move the content to the navbar when the siteNav is hidden #591

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure user docs #518

Restructure user docs #518

damithc commented Jan 1, 2019

yamgent left a comment

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

yamgent Jan 2, 2019

Chng-Zhi-Xuan commented Jan 2, 2019

Chng-Zhi-Xuan Jan 2, 2019

Chng-Zhi-Xuan Jan 2, 2019

Chng-Zhi-Xuan Jan 2, 2019

Chng-Zhi-Xuan Jan 2, 2019

Chng-Zhi-Xuan Jan 2, 2019 •

edited

Loading

yamgent commented Jan 2, 2019

Chng-Zhi-Xuan commented Jan 2, 2019

damithc commented Jan 2, 2019

yamgent commented Jan 3, 2019

acjh Jan 16, 2019

damithc Jan 16, 2019

yamgent Jan 17, 2019


		#### `titlePrefix`

		The prefix for all page titles. The separator <code>-</code> will be inserted by MarkBind. \|


		## Support for GFMD

		MarkBind supports additional Markdown features provided by Github-Flavored Markdown (GFMD). A summary is given below. Refer [Github's GFMD documentation](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) for more details.


		## Support for Nunjucks

		[Nunjucks](https://mozilla.github.io/nunjucks/) is a JavaScrip based templating tool. Here is a simple example:


		## <span class="glyphicon glyphicon-th-list" aria-hidden="true"></span> Features
		MarkBind can use Markdown documents to generate a <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 %%e.g., eLearning websites, online instruction manuals, project documentation etc.%%.


		<div class="indented">

		%%{{ icon_ticked }}%% a basic knowledge of Markdown and HTML syntax<br>


		#### Icons Fonts

		<small>%%Acknowledgement: Font Awesome icons are provided by [Font Awesome](https://fontawesome.com/) under their [free license](https://fontawesome.com/license) while Glyphicons are provided by [Glyphicons](https://glyphicons.com/) via Bootstrap 3.%%</small>

Restructure user docs #518

Restructure user docs #518

Conversation

damithc commented Jan 1, 2019

yamgent left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Chng-Zhi-Xuan commented Jan 2, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Chng-Zhi-Xuan Jan 2, 2019 • edited Loading

Choose a reason for hiding this comment

yamgent commented Jan 2, 2019

Chng-Zhi-Xuan commented Jan 2, 2019

damithc commented Jan 2, 2019

yamgent commented Jan 3, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Chng-Zhi-Xuan Jan 2, 2019 •

edited

Loading