Merge pull request #75 from mtmacdonald/cleanupDocs

Cleanup and modernise docs

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docgen-tool",
-  "version": "3.2.9",
+  "version": "3.2.10",
   "description": "A tool for creating HTML and PDF documentation",
   "main": "dist/docgen.js",
   "bin": {

src/docs/advanced-content.md

@@ -33,8 +33,7 @@
 }
 </style>
 
-Basic tables
-------------
+## Basic tables
 
 Basic tables can be inserted with the Github-flavoured Markdown
 [table extension](https://help.github.com/articles/github-flavored-markdown/#tables).
@@ -75,8 +74,7 @@ Basic tables can be inserted with the Github-flavoured Markdown
 </table>
 </div><br class="w-clear"/>
 
-HTML tables
------------
+## HTML tables
 
 Regular HTML can also be used for tables, allowing full custom styling (including table and column widths).
 
@@ -129,8 +127,7 @@ Regular HTML can also be used for tables, allowing full custom styling (includin
 </table>
 </div><br class="w-clear"/>
 
-Creating internal links to page sections
-----------------------------------------
+## Creating internal links to page sections
 
 To create links to other sections within one content page, put hyphens between the words in the heading and prepend with #:
 
@@ -141,15 +138,13 @@ To create links to other sections within one content page, put hyphens between t
 	This is a heading
 	-----------------
 
-Creating internal links to other pages
---------------------------------------
+## Creating internal links to other pages
 
 To create links to *other* content pages provide the relative url to the page:
 
 	[link to heading](example-page.html)
 
-Control of page breaks in the PDF
----------------------------------
+## Control of page breaks in the PDF
 
 DocGen does not provide precision control over PDF layout. However, some steps can be taken in case of page break
 issues (the most common problem).

src/docs/contents.json

@@ -11,10 +11,6 @@
       {
         "title": "Installation",
         "source": "installation.md"
-      },
-      {
-        "title": "Upgrading",
-        "source": "upgrading.md"
       }
     ]
   },
@@ -31,8 +27,8 @@
         "source": "writing-content.md"
       },
       {
-        "title": "CommonMark reference",
-        "source": "commonmark.md"
+        "title": "Markdown reference",
+        "source": "markdown.md"
       },
       {
         "title": "Advanced content",

src/docs/index.md

@@ -12,10 +12,10 @@ h3 {
   font-size: 24px;
   border-bottom: none;
 }
-
 #dg-content, #dg-innerContent {
   padding-top: 0;
 }
+
 #banner, #banner-buttons {
   margin: 0;
 }
@@ -118,7 +118,6 @@ p.browserSupport {
 }
 .browsers a {
   display: inline-block;
-  margin: 0 10px;
   vertical-align: top;
   width: 80px;
   padding: 10px;
@@ -370,12 +369,12 @@ automatically laid out according to a template. It is not intended as a precisio
      <li><strong>Install DocGen</strong></li>
      <li><strong>Scaffold an empty template</strong></li>
      <li><strong>Generate a static website</strong></li>
-    </ul
+    </ul>
     <p>Simply enter these commands in the terminal:</p>
   </div>
   <div class="column">
     <pre>
-<code>sudo npm install -g docgen-tool
+<code>npm install -g docgen-tool
 docgen scaffold
 docgen run -o $HOME/docgen-example</code></pre>
   </div>
@@ -387,4 +386,4 @@ docgen run -o $HOME/docgen-example</code></pre>
  </strong>
 </p>
 
-</div></div>
+</div></div>

src/docs/installation.md

@@ -1,49 +1,38 @@
 This section explains how to install DocGen.
 
-Supported platform
-------------------
+> NOTE - the websites and documents generated by DocGen can be used on all major operating systems and browsers without
+any setup or installation. These setup instructions are needed only when running the tool to generate documents.
 
-*'Supported platform'* means the software required to **run** the DocGen tool. The static website **produced** by 
-DocGen will work on all modern browsers on all all major operating systems 
-(see [browser support](index.html#browser-support)).
+DocGen is a command-line (CLI) tool. It runs on most major operating systems. 
 
-<p class="w-information">
-	The supported platform for this version of DocGen is: 
-	<strong>Ubuntu 14.04</strong> with <strong>Node.js 0.12.0</strong> 
-	and <strong>wkhtmltopdf 0.12.2.1 </strong>(with patched qt).
-</p>
+## Install Dependencies
 
-While other operating systems and dependency versions may work, they are not tested or officially supported.
+Before installing the tool, you need some dependencies.
 
-Dependencies
-------------
+### Node.js and NPM
 
-DocGen requires **[Node.js](https://nodejs.org)**. To install on Ubuntu Linux, enter these terminal commands:
+DocGen needs [Node.js](https://nodejs.org) (JavaScript engine) and its package manager [NPM](https://www.npmjs.com/)
+which are downloaded and installed together.
 
-	curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
-	sudo apt-get install -y nodejs
+See [Node.js downloads](https://nodejs.org/en/download) and choose the installer or package for you operating system.
 
-This method uses the 
-[NodeSource Linux Repositories](https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories)
-(recommended).
+- **Windows:** use the [official installer](https://nodejs.org/en/download) or [nvm-windows](https://github.com/coreybutler/nvm-windows)
+- **OS X:** use the [official installer](https://nodejs.org/en/download) or [nvm](https://github.com/nvm-sh/nvm)
+- **Ubuntu Linux:** use [nvm](https://github.com/nvm-sh/nvm) or see [other instructions](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-ubuntu-22-04)
 
-For other platforms (not supported), see the [download page](https://nodejs.org/download) or vendor instructions.
+### wkhtmltopdf (optional)
 
-Optional dependencies (only for PDF)
-------------------------------------
+The [wkhtmltopdf](http://wkhtmltopdf.org) package is optional and only needed if you want to enable generation of
+PDF documents.
 
-For optional PDF support, DocGen requires **[wkhtmltopdf](http://wkhtmltopdf.org)**. See the wkthmltopdf website for
-installation instructions.
+To install, [download the installer](https://wkhtmltopdf.org/downloads.html) or package for your operating system
+(choose the latest version).
 
-Quick install with NPM
-----------------------
+## Install DocGen
 
-The quickest way to install DocGen is with **[npm](https://www.npmjs.com)** (the JavaScript package manager). Enter 
-these terminal commands:
+The easiest way to install DocGen is through **[npm](https://www.npmjs.com)** (the JavaScript package manager). Enter 
+this terminal command:
 
-	sudo npm install -g docgen-tool
-
-Install by direct download
---------------------------
+	npm install -g docgen-tool
 
 DocGen can also be installed by [direct download](https://github.com/mtmacdonald/docgen).

src/docs/parameters.json

@@ -1,7 +1,7 @@
 {
   "title": "DocGen - a documentation tool",
   "name": "DocGen",
-  "version": "3.2.9",
+  "version": "3.2.10",
   "date": "27/09/2023",
   "organization": {
     "name": "Inkit Inc. and contributors",