Home

Welcome to the HQ of maintaining our visible open source projects. Our issues capture the planning process for their landing pages.

Our goal is consistent branding and wording across all of our visible projects. For example, they should all have the same header and footer.

Stay up to date with issue tracking on waffle.io.

Problem

Quick terminology:

• dox (dox site)

  The documentation site of a specific open-source project: formidable.com/open-source/victory/ is the victory dox site

• /docs

  A folder in the open-source project’s source repository that provides the content for the dox. Typically, the /docs folder contains .md (markdown) files.

• lander

  Only the homepage, or /index.html, of a dox site.

• *-docs

  There are two repositories in play: the source code for the open-source project, and the source code for the dox site. If the former is named project-x, then the latter will be named project-x-docs.

Requirements

1. The dox site must stay in sync with /docs folder (that lives in the GitHub repository’s source).
2. All dox should have the same content structure (with slight modifications between flagship and non-flagship projects).
3. All dox should have a consistently branded header and footer with Formidable logos in them.
4. All non-flagship dox should follow the Formidable brand guidelines (fonts, colors, spacey-ness, etc.).

Highly Recommended

• All dox should be deployed to formidable.com/open-source/proejct-x for easiest tracking on Google Analytics.

Questionable

• The site must be able to run locally offline. For example, a user should be able to run npm install project-x and then run npm run dox to see the same dox site that’s live at formidable.com/open-source/project-x.

Solution

Aside from the lander, the content for each dox site is generated directly from /docs through the use of ecology, or markdown-it, depending on whether component playground is needed or not. The expectation is that the /docs will update frequently, whereas the lander will not.

How are the sites deployed?

Each *-docs repo has a dependency on the latest master of the open source project.

"name": "project-x-docs",
"dependencies": {
  "project-x": "FormidableLabs/project-x"

Before building the dox site, project-x-docs pulls down the latest master, including any updates to /docs, using npm update.

"name": "project-x-docs",
"scripts": {
  "update-project": "npm update project-x"

Each *-docs repo is also hooked up to Travis. After running tests, Travis will build the dox site using the build-static command, which you can see in builder-docs-archetype, or by typing builder run in the terminal. Running build-static will clean any existing build, update the project, run the static site generator in webpack, and finally copy any static assets that don’t need to be run through webpack.

Travis uses encrypted environment variables to access formidable.com/open-source and runs a deploy script (deploy.sh), which will secure copy the /build folder it created and rename the folder to the appropriate project name.

Travis will automatically deploy a new version of the dox site on any push to the master branch of the *-docs repo.