Primer

Primer CSS is the Sass implementation of Primer, the design system that powers GitHub.

Install

This repository is distributed with npm. After installing npm, you can install @primer/css with this command.

$ npm install --save @primer/css

Usage

The included source files are written in Sass with the SCSS syntax. After installing with npm, you can add your project's node_modules directory to your Sass include paths (AKA load paths in Ruby), then import it like this:

@import "@primer/css/index.scss";

You can import individual Primer modules directly from the @primer/css package:

Then, you would import the module with:

@import "@primer/css/core/index.scss";
@import "@primer/css/product/index.scss";
@import "@primer/css/marketing/index.scss";

Development

See DEVELOP.md for development docs.

Releasing (Staff only)

You can find docs about our release process in RELEASING.md.

Documentation

The Primer CSS documentation site is created with Next and hosted on [Now].

Running the site

Once you've cloned this repo and run npm install, you can start the site with:

npm start

This should start up the Next dev server and a background task that will keep the pages directory up-to-date whenever you change the source files in modules/primer*.

Syncing the docs

If, for whatever reason, the dev server isn't syncing files, you have two choices:

1. Stop the server (ctrl-C) and restart it (npm run dev), which will re-sync the files and clear Next's cache.

2. Run script/sync manually:

   # in the docs directory
   script/sync
   

   If you find yourself needing to do this often, please file an issue and tag @shawnbot. 🙇

The pages directory

The pages directory contains all of the files that map to URLs on the site. Because we plan to host the site at primer.style/css (and because of the way that Now's path aliasing feature works), we nest all of our documentation under the additional css directory.

The sync task maintains a listing of files that it's copied from the modules directory in pages/css/.gitignore, which ensures that none of these files are checked into git.

Sync internals

We use Metalsmith to sync the source docs to the pages directory and transform them in the following ways:

1. We filter the list of files to only Markdown documents and package.json files
2. Many package README.mds wrap the actual documentation content in <!-- %docs --> HTML comments that usually include YAML frontmatter. In these instances, we extract the content that portion and reformat the frontmatter.
3. We filter out any Markdown files that don't include a path frontmatter key, and rename the destination file to match the path (e.g. path: foo/bar writes to pages/css/foo/bar.md).
4. We set the source frontmatter key to a fully-qualified github.com URL for the source file so that we can link directly to it.
5. A limited list of fields for all packages is extracted into a single file (pages/css/packages.json), which serves as a light-weight dependency graph.
6. We read the changelog and write it to whats-new/changelog.md with some additional frontmatter.
7. We read the list of files from pages/css/.gitignore and delete them from the filesystem, then write the new list of paths so that they aren't committed to git.

All of the logic for syncing the source docs (and transforming them in transit) is controlled in lib/sync.js, and each "step" in the transformation (as well as the watching) is implemented as a Metalsmith plugin.

Why Metalsmith? We're glad you asked! @shawnbot likes the simplicity of Metalsmith's core and how easy it is to write powerful plugins.

License

MIT © GitHub