Deployment and previews on Docsy

Deployment with Amazon S3 and CloudFront

Mon, 01 Jan 0001 00:00:00 +0000

There are several options for publishing your web site using Amazon Web Services. This section describes the most basic option, deploying your site using an S3 bucket and activating the CloudFront CDN (content delivery network) to speed up the delivery of your deployed contents.

After your registration at AWS, create your S3 bucket, connect it with your domain, and add it to the CloudFront CDN. This blog post has all the details and provides easy to follow step-by-step instructions for the whole procedure.

Chrome build modes

Mon, 01 Jan 0001 00:00:00 +0000

A docs site re-emits the same auto-generated chrome — the navbar, footer, and left-nav — on every page, even though those regions are usually identical site-wide. That repetition slows the build, bloats the output, and slows anything that processes every page, such as a link checker; it also makes for noisy output diffs.

Use the td.chrome parameter to select one of two build modes:

full (default) emits each page’s chrome on the page itself, ready for any client. Any td.chrome value other than shared is treated as full, so a typo fails safe.
shared emits each region on just one donor page per locale and restores it on the other pages in the browser with a small script. The output stays lean, while readers still get the full navigation once the page loads.

Web dev note

shared mode is in the spirit of the app-shell pattern but applied to page chrome, where a single region instance is fetched from its donor and restored on the client, over an otherwise static multi-page site.

Deployment on GitHub Pages

Mon, 01 Jan 0001 00:00:00 +0000

If your repo is hosted on GitHub, a simple option is to serve your site with GitHub Pages. GitHub Pages lets you create project, user, and organization sites; for a project site, your site URL will be http(s)://<username>.github.io/<repository_name>, custom domains are also supported. GitHub Pages come with continuous deployment using GitHub actions, while the marketplace for actions has useful tools for spell and link checking, deploy previews, and more. Using your existing GitHub account, you can start by using the free plan for publicly available repositories, with premium tiers available for business use cases.

Serving your site locally

Mon, 01 Jan 0001 00:00:00 +0000

Depending on your deployment choice you may want to serve your site locally during development to preview content changes. To serve your site locally:

Ensure you have an up to date local copy of your site files cloned from your repo.
Ensure you have the tools described in Prerequisites and installation installed on your local machine, including postcss-cli (you’ll need it to generate the site resources the first time you run the server).

Deployment on Netlify

Mon, 01 Jan 0001 00:00:00 +0000

We recommend using Netlify as a particularly simple way to serve your site from your Git provider (GitHub, GitLab, or BitBucket), with continuous deployment, previews of the generated site when you or your users create pull requests against the doc repo, and more. Netlify is free to use for Open Source projects, with premium tiers if you require greater support.

Before deploying with Netlify, make sure that you’ve pushed your site source to your chosen GitHub (or other provider) repo, following any setup instructions in Using the theme.