Building the Website

This documents the way the website is built and deployed with Netlify.

For how to deploy historical versions to GitHub pages visit https://github.com/vmware/clarity/wiki/Building-the-Website-with-GitHub-Pages.

Previewing locally

The website is part of the project, inside of src/website (pre-v4) and packages/angular/projects/website (v4). As part of your development, you can preview the website at any time by running the following and previewing it at http://localhost:4200.

Pre 4.0

npm run website:start

4.0 (from clarity folder)

yarn run angular:website:build // sometimes this command is necessary if the website has never been built on a branch before...
yarn run angular:website:serve

Note that if you are on a clean fork or clone of the Clarity project, you may have to go down into /clarity/packages/angular and run yarn run website:news.

Downloadable assets

Any large assets, such as icon zips and Sketch files are meant to be kept in the https://github.com/vmware/clarity-assets repository. The website links to these files directly to spare the complexity of hosting these files in our main repository project.

For images that we use in our documentation, those remain in the clarity repository under the src/website/src/assets directory.

Adding a new release

To add a new release, you need to update a few files and create a release template.

Pre 4.0

• src/website/src/releases/{MAJOR}/{VERSION}.html - Add a new html file at this location with the release notes (usually easiest to copy an existing one and update it).
• src/website/src/releases/release-list.json - If this release is the new latest version, update the current property at the top with the new version number. Then add a new object to all in the same format with a date, sketch file version, and the commit ID of the release commit.
• src/website/src/releases/release-template-stub.json - Add a new line to this file with the version number and the file path to the HTML file.

4.0

• packages/angular/projects/website/src/releases/{MAJOR}/{VERSION}.html - Add a new html file at this location with the release notes (usually easiest to copy an existing one and update it).
• packages/angular/projects/website/src/releases/release-list.json - If this release is the new latest version, update the current property at the top with the new version number. Then add a new object to all in the same format with a date, sketch file version, and the commit ID of the release commit.
• packages/angular/projects/website/src/releases/release-template-stub.json - Add a new line to this file with the version number and the file path to the HTML file.

Versioning

v4

To edit the v4 website or documentation use the website folder on the v4 branch. Commits merged into the master branch will trigger an automatic deploy for Netlify.

v3

To edit the v3 website or documentation use the website folder on the v3 branch. Commits merged into the v3 branch will trigger an automatic deploy for Netlify.

v2

To edit the v2 website or documentation use the website folder on the v2 branch. Commits merged into the v2 branch will trigger an automatic deploy for Netlify.

v1

To edit the v1 documentation use the website folder on the v1 branch. Commits merged into the v1 branch will trigger an automatic deploy for Netlify.

Website scripts

In our package.json file, there are a set of scripts that are all prefixed with website (pre 4.0) or angular:website (in 4.0). This is what each of them does.

4.0

• angular:website:build - This runs the website build process, which includes a prod build of the website, a production build of the server, and compiles the server and prerender scripts.
• angular:website:serve - This starts the local server for development, but also ensures you've built the news template first.

3.0

• website:build - This runs the website build process, which includes a prod build of the website, a production build of the server, and compiles the server and prerender scripts.
• website:start - This starts the local server for development, but also ensures you've built the news template first.
• website:render - This runs the prerender script that ultimately outputs the precompiled index.html files.
• website:preview - This starts a local server for previewing the prerendered site.

Pre 3.0

• website:compile - This compiles the server and prerender scripts from TypeScript to JavaScript so we can run with with Node.
• website:server - This runs the server which has the web application embedded inside, allowing it to take requests and return a compiled route.
• website:build - This runs the website build process, which includes a prod build of the website, a production build of the server, and compiles the server and prerender scripts.
• website:start - This starts the local server for development, but also ensures you've built the news template first.
• website:render - This runs the prerender script that ultimately outputs the precompiled index.html files.
• website:news - This generates the news template files, which needs to be run whenever you change the releases information.
• website:prerender - This runs the news, build, and render steps to do a complete prerendering process.
• website:preview - This starts a local server for previewing the prerendered site.

Deploying the Website

The website now runs on Netlify, so you'll need an account first, if you don't check with the Clarity team to get added (only for Clarity team maintainers).

Log in to Netlify, find the version that you just deployed in the Deploys tab, and then publish it by clicking on the Publish/Deploy button. If the version you deployed is missing from the list of deployments, then it means your deploy failed. Note you can also find your version by the Git commit hash.

Once you run a publish/deploy, it will be live on the Clarity website.

We do not have automatic deploys turned on, so please do not turn it on at this time.