mulesoft-docs-site-generator v1.1.0

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