mulesoft-docs-site-generator
v1.1.0
Published
An opinionated multi-repository static site generator for making documentation sites.
Downloads
2
Readme
= MuleSoft Documentation Site Generator
A multi-repository static site generator for creating MuleSoft's documentation site.
== Prerequisites
// What software do I need to have installed on my system? (e.g., Node 7, yarn, C development libraries?)
To run this site generator, you'll need https://nodejs.org/[Node.js] 7.9.0+ and https://yarnpkg.com/[Yarn] (an alternative package manager).
Node.js:: You can install Node.js from the official packages but we strongly recommend that you use https://github.com/creationix/nvm[nvm] to install and manage Node.
Yarn:: If you aren't already using https://yarnpkg.com/[Yarn], you can install it through npm: + [source, bash] npm install --global yarn
== How to Get Started?
// What do I need to do before executing the generator the first time? (e.g., run yarn)
First you need to install local dependencies with Yarn:
[source, bash] yarn install
Once all dependencies are installed, you'll be able to run the site generator.
== What to Expect?
// What does the generator do when I run it (at a high level)? (i.e., what should I expect to happen as it stands today)
Basically, the generator gets all AsciiDoc files from MuleSoft's git repositories and transforms them to HTML. It also produces a listing of all encountered files.
In details, the generator goes through all these steps:
. Reads a list a public git repositories (in site.js
for now) and clones them.
. Scans all files from all branches of all repositories and produce a stream of vinyl files (virtual in-memory files with metadatas).
. Extracts coordinates from each files: component, module, version...
. Reads AsciiDoc documents.
. Converts AsciiDoc documents to HTML.
. Change destination paths according to output rules.
. Produces a report listing of all the scanned files in build/site/vinyl-collection-report.txt
. The report looks like this:
+
[source]
https://github.com/organization/project-one.git/ branch-foo/ file.adoc branch-bar/ file.adoc https://github.com/organization/project-two.git/ master/ subfolder/ foobar.adoc
. Write vinyl files on disk in build/site
.
== How to Build the Site?
// How do I execute the generator? (e.g., node site.js)
To build the site, you just need to run:
[source, bash] node site.js
== How to View the Site?
// Where can I find the generated site? How do I view it?
The "site" is located in build/site
.
Here, you'll find all the generated HTML files and the report in vinyl-collection-report.txt
.