Restructure user docs by damithc · Pull Request #518 · MarkBind/markbind

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

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


Missing comma at the end of this line

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

+
+#### **`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

+* **`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

+
+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

+
+## 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

+
+## 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

+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

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


bookFiles

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

+...
+```
+
+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

+<big>**Generate dynamic websites from Markdown text.**</big>

-## <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

+
+<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

+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

+
+#### 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


 ```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

+  <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


		#### `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:


		<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>

Conversation

damithc commented Jan 1, 2019

Uh oh!

yamgent left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Chng-Zhi-Xuan commented Jan 2, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Chng-Zhi-Xuan Jan 2, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yamgent commented Jan 2, 2019

Uh oh!

Chng-Zhi-Xuan commented Jan 2, 2019

Uh oh!

damithc commented Jan 2, 2019

Uh oh!

yamgent commented Jan 3, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Chng-Zhi-Xuan Jan 2, 2019 •

edited

Loading