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. See the issues across all the docs sites on waffle.io.

👉 How do I use <Header> and <Footer> components?

👉 How do I deploy my project’s docs site?

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.