Documentation website

.github/workflows/deploy-website.yaml

@@ -0,0 +1,38 @@
+name: Deploy Website
+
+on:
+  push:
+    branches:
+      - trunk
+    paths:
+      - 'README.md'
+      - 'docs/**'
+      - 'website/**'
+
+jobs:
+  deploy:
+    name: Deploy Website
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          publish_dir: ./website/build
+          external_repository: carbon-language/carbon-language.github.io
+          publish_branch: trunk
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

README.md

@@ -1,38 +1,35 @@
-# Carbon Language: <br/> An experimental successor to C++
+# Carbon Language: an experimental successor to C++
 
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
 Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
+<!-- Keep these links on one line so the pipes are spaced correctly on the website. -->
 <p align="center">
-  <a href="#why-build-carbon">Why?</a> |
-  <a href="#language-goals">Goals</a> |
-  <a href="#project-status">Status</a> |
-  <a href="#getting-started">Getting started</a> |
-  <a href="#join-us">Join us</a>
+  <a href="#why-build-carbon">Why?</a> | <a href="#language-goals">Goals</a> | <a href="#project-status">Status</a> | <a href="#getting-started">Getting started</a> | <a href="#join-us">Join us</a>
 </p>
 
 **See our [announcement video](https://youtu.be/omrY53kbVoA) from
 [CppNorth](https://cppnorth.ca/).** Note that Carbon is
 [not ready for use](#project-status).
 
-<a href="docs/images/snippets.md#quicksort">
 <!--
 Edit snippet in docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="docs/images/snippets.md#quicksort">
 <img src="docs/images/quicksort_snippet.svg" align="right" width="575"
-     alt="Quicksort code in Carbon. Follow the link to read more.">
+     alt="Quicksort code in Carbon. Follow the link to read more."/>
 </a>
 
 <!--
 Don't let the text wrap too narrowly to the left of the above image.
 The `div` reduces the vertical height.
 GitHub will autolink `img`, but won't produce a link when `href="#"`.
 -->
-<div><a href="#"><img src="docs/images/bumper.png"></a></div>
+<div><a href="#"><img src="docs/images/bumper.png"/></a></div>
 
 **Fast and works with C++**
 
@@ -169,37 +166,37 @@ familiar and be easy to read and understand.
 
 C++ code like this:
 
-<a href="docs/images/snippets.md#c">
 <!--
 Edit snippet in docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="docs/images/snippets.md#c">
 <img src="docs/images/cpp_snippet.svg" width="600"
-     alt="A snippet of C++ code. Follow the link to read it.">
+     alt="A snippet of C++ code. Follow the link to read it."/>
 </a>
 
 corresponds to this Carbon code:
 
-<a href="docs/images/snippets.md#carbon">
 <!--
 Edit snippet in docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="docs/images/snippets.md#carbon">
 <img src="docs/images/carbon_snippet.svg" width="600"
-     alt="A snippet of converted Carbon code. Follow the link to read it.">
+     alt="A snippet of converted Carbon code. Follow the link to read it."/>
 </a>
 
 You can call Carbon from C++ without overhead and the other way around. This
 means you migrate a single C++ library to Carbon within an application, or write
 new Carbon on top of your existing C++ investment. For example:
 
-<a href="docs/images/snippets.md#mixed">
 <!--
 Edit snippet in docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="docs/images/snippets.md#mixed">
 <img src="docs/images/mixed_snippet.svg" width="600"
-     alt="A snippet of mixed Carbon and C++ code. Follow the link to read it.">
+     alt="A snippet of mixed Carbon and C++ code. Follow the link to read it."/>
 </a>
 
 Read more about

docs/project/faq.md

@@ -168,24 +168,24 @@ expect the vast majority of code to interoperate well.
 
 For example, considering a pure C++ application:
 
-<a href="/docs/images/snippets.md#c">
 <!--
 Edit snippet in /docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="/docs/images/snippets.md#c">
 <img src="/docs/images/cpp_snippet.svg" width="600"
-     alt="A snippet of C++ code. Follow the link to read it.">
+     alt="A snippet of C++ code. Follow the link to read it."/>
 </a>
 
 It's possible to migrate a single function to Carbon:
 
-<a href="/docs/images/snippets.md#mixed">
 <!--
 Edit snippet in /docs/images/snippets.md and:
 https://drive.google.com/drive/folders/1-rsUjiya7dSZ87L8kpZmu3MZghRVxzLA
 -->
+<a href="/docs/images/snippets.md#mixed">
 <img src="/docs/images/mixed_snippet.svg" width="600"
-     alt="A snippet of mixed Carbon and C++ code. Follow the link to read it.">
+     alt="A snippet of mixed Carbon and C++ code. Follow the link to read it."/>
 </a>
 
 References:

proposals/p0555.md

@@ -96,7 +96,7 @@ left-to-right arrow meaning a left-associative operator.
 For example:
 
 <div align="center">
-<img src="p0555/example.svg" alt="Example operator precedence diagram">
+<img src="p0555/example.svg" alt="Example operator precedence diagram"/>
 </div>
 
 ... would depict a higher-precedence `*` operator and a lower-precedence `+`

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,53 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm install
+```
+
+### Local development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true npm run deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> npm run deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+### Setting up GitHub Actions auto-deployment
+
+The [deployment workflow](../.github/workflows/deploy-website.yaml) is configured to deploy to `carbon-language.github.io` using [deploy keys](https://docs.github.com/en/developers/overview/managing-deploy-keys).
+(Personal access tokens can also be used via [`personal_token`](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-deploy-to-external-repository-external_repository).)
+
+To configure the required deploy keys:
+
+1. Create a new SSH key pair according to the [GitHub docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key).
+2. Add the private key to the "Repository secrets" section of repository which runs the workflow, name it `ACTIONS_DEPLOY_KEY`.
+3. Add the public key to the "Deploy keys" section of the target deployment repository and enable "Allow write access".
+4. The next time the GitHub Actions workflow runs, it will use these keys to deploy the website.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docusaurus.config.js

@@ -0,0 +1,113 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const transformLinks = require('./src/plugins/transformLinks');
+const transformImageLinks = require('./src/plugins/transformImageLinks');
+const removeTableOfContents = require('./src/plugins/removeTableOfContents');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'Carbon Language',
+  tagline: 'An experimental successor to C++',
+  url: 'https://carbon-language.github.io',
+  baseUrl: '/',
+  onBrokenLinks: 'ignore', // TODO: Fix broken links, and change this back to 'throw'
+  onBrokenMarkdownLinks: 'ignore', // These are fixed in `transformLinks`.
+  favicon: 'img/carbon-logo.png',
+
+  // GitHub pages deployment config.
+  organizationName: 'carbon-language',
+  projectName: 'carbon-language.github.io',
+  trailingSlash: true, // Fixes relative directory links on e.g. Spec page.
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          path: '..',
+          routeBasePath: '/',
+          include: ['docs/**/*.{md,mdx}', 'README.md'],
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl: 'https://github.com/carbon-language/carbon-lang/blob/trunk/docs',
+          beforeDefaultRemarkPlugins: [removeTableOfContents, transformLinks],
+          rehypePlugins: [transformImageLinks],
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+  /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      colorMode: {
+        defaultMode: 'light',
+        disableSwitch: false,
+        respectPrefersColorScheme: true,
+      },
+      announcementBar: {
+        content: '⚠️ Carbon is experimental and not production-ready, see ' +
+          '<a href="/docs/project/faq#how-soon-can-we-use-carbon">How soon can we use Carbon?</a>',
+        backgroundColor: 'var(--ifm-navbar-background-color)',
+        textColor: 'var(--ifm-font-color-base)',
+        isCloseable: true,
+      },
+      navbar: {
+        title: 'Carbon Language',
+        logo: {
+          alt: 'Carbon Logo',
+          src: 'img/carbon-logo.png',
+        },
+        items: [
+          { to: '/docs/design', label: 'Design', position: 'left' },
+          { to: '/docs/project', label: 'Project', position: 'left' },
+          { to: '/docs/guides', label: 'Guides', position: 'left' },
+          { to: '/docs/spec', label: 'Spec', position: 'left' },
+          {
+            href: 'https://github.com/carbon-language/carbon-lang',
+            label: 'GitHub',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Community',
+            items: [
+              {
+                label: 'GitHub',
+                href: 'https://github.com/carbon-language/carbon-lang',
+              },
+              {
+                label: 'Discord',
+                href: 'https://discord.gg/ZjVdShJDAs',
+              },
+              {
+                label: 'Code of Conduct',
+                href: 'https://github.com/carbon-language/carbon-lang/blob/trunk/CODE_OF_CONDUCT.md',
+              },
+            ],
+          },
+        ],
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+      },
+    }),
+};
+
+module.exports = config;