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.

Sites

Docs	Repo	Site	npm
builder	builder-docs	/open-source/builder	builder-docs
component-playground	component-playground-docs	/open-source/component-playground	component-playground-docs
formidable-charts	formidable-charts-docs	/open-source/formidable-charts	formidable-charts-docs
formidable-playbook	formidable-playbook-docs	/open-source/playbook	formidable-playbook-docs
radium	radium-docs	/open-source/radium	radium-docs
spectacle	spectacle-docs	/open-source/spectacle	*formidable-spectacle-docs
spectacle-editor	spectacle-editor-docs	/open-source/spectacle-editor	spectacle-editor-docs
victory	victory-docs	/open-source/victory	victory-docs

*Name differs between npm package and github repository

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/project-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"