Static CMS

A static documentation site that can be forked and updated for any project. Examples include the NYC Benefits Platform, Benefits Screening API documentation.

Updating the static site front-end

The site source is written in JavaScript (ES Module format), Dart Sass, and Twig templates. The source is compiled by the Patterns CLI (more details below) with some custom commands and configuration.

Getting started

1. Fork this repository. A public facing repository is required for the CMS to pull content from.

2. Clone the repository locally and run the NPM commands below or start editing the content in the content branch following the content management instructions.

NPM

Install dependencies by running the following command;

$ npm i

Then start the development server and asset watcher;

$ npm start

This will set the NODE_ENV to development which tells the development server to watch for specific file changes in the ./src directory (the CLI will print the globing patterns that are being watched) and compile views and assets into the ./dist/drafts directory. The site's main script will pull content in Markdown files from the drafts content branch of this repository.

The drafts directory serves as the local development site preview and the content preview in the production site. See Content Management below for more details.

The public-facing site is stored in the root of the ./dist directory. To preview the public-facing site locally and view published content in the content branch use the following command;

$ npm run production

This will set the NODE_ENV to production but and run the same development server and source file watcher/compiler.

Patterns CLI

The site uses the Patterns CLI, also maintained by @nycopportunity, to build source files from the ./src directory to the ./dist directory. All of the commands from the CLI are available for compiling different asset types. It uses the Patterns Twig Plugin in place of the Slm Lang compiler for templating.

The CLI is configured by scripts in the ./config directory (each command in the CLI can have local project configuration). The build paths for production and development are set in the ./config/global.js

Custom commands that extend the Patterns CLI are stored in the ./bin directory.

CDN Path

The path to the content CDN is stored in the package.json. This is where the content branch is mapped to the production and the drafts branch is mapped to development.

Migrate changes back to main

After changes are made, create a pull request to migrate changes from your feature branch back into env/development. When the changes are approved by another developer create a merge commit or squash and merge (preferably squash for feature branches). Create and merge/squash another pull request from env/development into main.

Publishing

The public-facing site (and drafts directory for content managers) is published from the ./dist directory to the gh-pages branch of this repository. To publish changes check out the main branch. Tag the repository with the latest version using the npm version {{ major / minor / patch }} command. For example;

$ npm version minor

Then run the ghpages npm script build in production mode and then deploy to the GitHub Pages site.

$ npm run ghpages

Content management

The content is managed in the content branch using Markdown files. To edit these files and move them from draft to published follow these instructions;

Drafting content

Content is drafted in the drafts branch.

1. Viewing files. View the table of contents in the drafts README file to find a link to each page's content source.

2. Editing files. When you are on the file's page you will see the rendered Markdown preview. Click the pencil icon in the top right corner, just above the preview. Once you are in edit mode you can make and preview changes using GitHub Flavored Markdown syntax. View GitHub's guide on editing files in GitHub to learn more.

3. Commit changes. When you are done making changes you will commit your changes with a message reflecting the scope of the change. The commit description underneath the message is optional. Commit directly to the drafts branch.

Preview

You can now view drafted changes in the site in the drafts directory on the public site.

Creating a pull request for review

When you are done drafting changes create a new pull request to stage changes from the drafts branch to the content branch.

1. Create a new pull request by going to ./compare or go to the Pull Requests tab at the top of the repository page then click New pull request.

2. In the Compare changes page change the base branch from base:main to content and the compare branch from compare:main branch to drafts.

3. You will be able to see a preview of the changes in your pull request. Click Create pull request to create a title, description, and add reviewers. View GitHub's guide on creating pull requests to learn more.

4. Click Create pull request again in the next view to make the pull request.

Publishing content

Once the pull request is approved changes are ready to be published. Click Merge pull request. The content will be live.

---

The Mayor's Office for Economic Opportunity is committed to sharing open source software that we use in our products. Feel free to ask questions and share feedback. Interested in contributing? See our open positions on buildwithnyc.github.io. Follow our team on GitHub @nycopportunity and @cityofnewyork:nycopportunity or browse our work on Github.