Build a website. (#4189)

Demo site: https://jonmeow.carbon-lang.dev/

I'm trying to keep work under the `/website` subdirectory so that the
misc files don't interfere with unrelated views of the repository. The
`prebuild.py` script does some work to move things around and add
frontmatter, helping the jekyll generation.

I'm using the "just-the-docs" theme because I think it's a decent match
for what we want, and getting jekyll up and running with it wasn't too
difficult. Note #1526 proposed using Docusaurus; I started out there,
but was having trouble getting it working with newer versions. The
plugins in particular I got stuck trying to make work, which sent me
looking for options that we could have working with less customization.
I do lean towards jekyll though, because it's what GH uses so hopefully
we can get a more consistent experience.

Having a website has been approved for a while under #1492, but hasn't
been a priority. I'm mainly doing this because I want to just be able to
point people to carbon-lang.dev and have easy links that way.

---------

Co-authored-by: Chandler Carruth <[email protected]>

.codespell_ignore

@@ -16,4 +16,5 @@ inout
 parameteras
 pullrequest
 rightt
+rouge
 statics

.github/workflows/gh_pages_ci.yaml

@@ -0,0 +1,41 @@
+# 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
+
+name: GitHub Pages CI
+
+on:
+  pull_request:
+
+# Cancel previous workflows on the PR when there are multiple fast commits.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Prebuild actions
+        run: ./website/prebuild.py
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@a6e6f86333f0a2523ece813039b8b4be04560854 # v1.190.0
+        with:
+          # Runs 'bundle install' and caches installed gems automatically.
+          bundler-cache: true
+          # Increment this number if you need to re-download cached gems.
+          cache-version: 0
+      - name: Build with Jekyll
+        run: bundle exec jekyll build

.github/workflows/gh_pages_deploy.yaml

@@ -0,0 +1,76 @@
+# 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
+
+name: GitHub Pages deploy
+
+on:
+  # Runs on pushes targeting the default branch.
+  push:
+    branches: ['trunk']
+
+  # Allows you to run this workflow manually from the Actions tab.
+  workflow_dispatch:
+
+# Cancel previous workflows on the PR when there are multiple fast commits.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Prebuild actions
+        run: ./website/prebuild.py
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@a6e6f86333f0a2523ece813039b8b4be04560854 # v1.190.0
+        with:
+          # Runs 'bundle install' and caches installed gems automatically.
+          bundler-cache: true
+          # Increment this number if you need to re-download cached gems.
+          cache-version: 0
+      - name: Build with Jekyll
+        env:
+          JEKYLL_ENV: production
+        run: |
+          bundle exec jekyll build --verbose \
+            --source ./ \
+            --destination ./_site \
+            --baseurl "${{ steps.pages.outputs.base_path }}"
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by
+        # default.
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
+        with:
+          egress-policy: audit
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.pre-commit-config.yaml

@@ -180,7 +180,7 @@ repos:
             Exceptions. See /LICENSE for license information.
             SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
           - --custom_format
-          - '\.(carbon|c|json|proto|ypp)(\.tmpl)?$'
+          - '\.(carbon|c|json|proto|scss|ypp)(\.tmpl)?$'
           - ''
           - '// '
           - ''
@@ -216,6 +216,8 @@ repos:
               compile_flags.txt|
               github_tools/requirements.txt|
               third_party/.*|
+              website/.ruby-version|
+              website/Gemfile.lock|
               .*\.def|
               .*\.svg|
               .*/fuzzer_corpus/.*|

SECURITY.md

@@ -1,19 +1,19 @@
+# Security policy
+
 <!--
 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
 -->
 
-# Security policy
-
 It's important to us that the Carbon Language provides a secure implementation.
 Thank you for taking the time to report vulnerabilities.
 
 The Carbon Language is still an
 [experimental project](/README.md#project-status), so please be careful if using
 it in security-sensitive environments.
 
-# Reporting a vulnerability
+## Reporting a vulnerability
 
 Please use
 <https://github.com/carbon-language/carbon-lang/security/advisories/new> to

docs/images/snippets.md

@@ -6,6 +6,11 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
+<!--
+{% raw %}
+Hides `{{` from jekyll's liquid parsing. Note endraw at the bottom.
+-->
+
 ## Images
 
 Images are managed in
@@ -138,3 +143,7 @@ auto main() -> int {
   return 0;
 }
 ```
+
+<!--
+{% endraw %}
+-->

explorer/README.md

@@ -6,6 +6,11 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
+<!--
+{% raw %}
+Hides `{{` from jekyll's liquid parsing. Note endraw at the bottom.
+-->
+
 `explorer` is an implementation of Carbon whose primary purpose is to act as a
 clear specification of the language. As an extension of that goal, it can also
 be used as a platform for prototyping and validating changes to the language.
@@ -334,3 +339,7 @@ information and provide visual separation for different sections.
 - - - - -  Sub Heading - - - - -
 --------------------------------
 ```
+
+<!--
+{% endraw %}
+-->

explorer/ast/README.md

@@ -1,3 +1,5 @@
+# Explorer AST
+
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
 Exceptions. See /LICENSE for license information.

explorer/syntax/README.md

@@ -1,3 +1,5 @@
+# Explorer Syntax
+
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
 Exceptions. See /LICENSE for license information.

testing/README.md

@@ -0,0 +1,9 @@
+# Testing
+
+<!--
+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
+-->
+
+Testing-specific libraries.

testing/file_test/README.md

@@ -6,6 +6,11 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
+<!--
+{% raw %}
+Hides `{{` from jekyll's liquid parsing. Note endraw at the bottom.
+-->
+
 ## BUILD
 
 A typical BUILD target will look like:
@@ -156,3 +161,7 @@ Supported comment markers are:
     Tips like this are added by autoupdate, for example providing commands to
     run the test directly. Tips have no impact on validation; the marker informs
     autoupdate that it can update or remove them as needed.
+
+<!--
+{% endraw %}
+-->

website/.ruby-version

@@ -0,0 +1 @@
+3.3

website/404.md

@@ -0,0 +1,12 @@
+---
+title: 404
+nav_exclude: true
+---
+
+# 404: File not found
+
+<!--
+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
+-->

website/Gemfile

@@ -0,0 +1,14 @@
+# 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
+
+source 'https://rubygems.org'
+
+gem "jekyll", "4.3.3"
+gem "just-the-docs", "0.8.2"
+
+group :jekyll_plugins do
+  gem "jekyll-default-layout", "0.1.5"
+  gem "jekyll-readme-index", "0.3.0"
+  gem "jekyll-relative-links", "0.7.0"
+end

website/Gemfile.lock

@@ -0,0 +1,100 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    bigdecimal (3.1.8)
+    colorator (1.1.0)
+    concurrent-ruby (1.3.4)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.27.3-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.27.3-x86_64-linux)
+      bigdecimal
+      rake (>= 13)
+    http_parser.rb (0.8.0)
+    i18n (1.14.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-default-layout (0.1.5)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-relative-links (0.7.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.8.2)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (6.0.1)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.3.5)
+      strscan
+    rouge (4.3.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.77.8)
+      google-protobuf (~> 4.26)
+      rake (>= 13)
+    strscan (3.1.0)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll (= 4.3.3)
+  jekyll-default-layout (= 0.1.5)
+  jekyll-readme-index (= 0.3.0)
+  jekyll-relative-links (= 0.7.0)
+  just-the-docs (= 0.8.2)
+
+BUNDLED WITH
+   2.5.17