mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-24 20:10:13 +01:00
Jon Ross-PerkinsandChandler Carruth
b6396e97f8
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 <chandlerc@gmail.com>
60 lines
1.9 KiB
Markdown
60 lines
1.9 KiB
Markdown
# Documentation website
|
|
|
|
<!--
|
|
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
|
|
-->
|
|
|
|
<!-- toc -->
|
|
|
|
## Table of contents
|
|
|
|
- [Overview](#overview)
|
|
- [Build process](#build-process)
|
|
- [Development tips](#development-tips)
|
|
- [Domain configuration](#domain-configuration)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## Overview
|
|
|
|
Carbon's main website is the GitHub project page. Carbon remains too early and
|
|
experimental to have a full-fledged website.
|
|
|
|
This directories contains infrastructure for building the convenience
|
|
documentation website, which should be at <https://docs.carbon-lang.dev>.
|
|
|
|
## Build process
|
|
|
|
Website generation is done by
|
|
[gh_pages_deploy.yaml](/.github/workflows/gh_pages_deploy.yaml). It runs
|
|
`prebuild.py`, which prepares files for website generation, then builds the
|
|
website using Jekyll, configured through `_config.yml`.
|
|
|
|
## Development tips
|
|
|
|
[rbenv](https://github.com/rbenv/rbenv) can be used to set up Ruby and `bundle`.
|
|
|
|
To run a server, run `bundle exec jekyll serve`. See
|
|
[Jekyll docs](https://jekyllrb.com/docs/usage/) for more commands.
|
|
|
|
To update the `Gemfile.lock` after `Gemfile` changes, run `bundle update`.
|
|
|
|
## Domain configuration
|
|
|
|
The
|
|
[custom domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site)
|
|
is configured in three places:
|
|
|
|
- GitHub organization
|
|
[verified domains](https://github.com/organizations/carbon-language/settings/pages)
|
|
- GitHub repository
|
|
[custom domain](https://github.com/carbon-language/carbon-lang/settings/pages)
|
|
- Google Cloud DNS
|
|
- This is visible with `dig docs.carbon-lang.dev`
|
|
|
|
Note all of these require admin permissions to modify. For sharing test pages, a
|
|
GitHub user and repository can be used, pushing to `<username>.github.io` (or
|
|
getting a custom DNS setup).
|