carbon-lang

carbon-lang copied to clipboard

Closes #1492. Adds a website that is auto-generated from the markdown files in the repo, using Docusaurus. This will make it easier to browse the docs, by adding a navigation sidebar as well as a table-of-contents sidebar, mobile support, and other things. The site can be autodeployed to https://carbon-language.github.io/ (or to a custom domain using a CNAME file), and is currently configured accordingly (deployment instructions in website/README.md).

• The front page is generated from the repository root readme.
• The top navigation items Design, Project, Guides, and Spec corresponds to the respective directories under docs/.
• Footer has links to GitHub repo, Discord, and Code of Conduct.

Preview: https://emlai.github.io/

To do:

• [ ] Render mermaid diagrams.
• [ ] Before or after merging, for someone with admin access to the organization: Create carbon-language.github.io repo, enable GitHub Pages for it, and configure deploy keys (instructions). You can ping me (emlai#9471) on Discord if you need help.

Follow-up improvements (non-blocking tasks that are not necessary for merging this PR):

• [ ] Mention in docs that they get auto-deployed to the website when a change is pushed to trunk.
• [ ] Add site-wide search such as Algolia which will scrape the site and host the search index in their own database. Requires that the site is deployed first before setting up.
• [ ] Fix broken links and enable Docusaurus link validation (src), blocked by Docusaurus issue: https://github.com/facebook/docusaurus/issues/7829
• [ ] Fix description meta tags, currently <!--: <meta data-rh="true" name="description" content="<!--">

How to test

Go to https://emlai.github.io/ and check that links, navigation, etc. works, and everything looks ok.

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@emlai, How can I contribute to the Documentation Website?

What if, we use the CppNorth video as iframe in the website instead of using the video link?

@nomandhoni-cs Hi! You can contribute by making a PR to this branch in my fork. We can sync on the Carbon Discord, I'm emlai#9471 there.

As for converting youtube links into embeds in the markdown, it should be possible using remark plugins such as https://github.com/agentofuser/remark-oembed.

Depends on #1492

This is looking really promising!

It looks like mermaid diagrams aren't being rendered by this documentation generation pipeline: for example, the precedence diagram at https://emlai.github.io/docs/design/expressions/ is rendered as text. It looks like there's an external implementation of mermaid rendering for docusaurus available already, and native support coming soon.

We triage inactive PRs and issues in order to make it easier to find active work. If this PR should remain active, please comment or remove the inactive label. This PR is labeled inactive because the last activity was over 90 days ago. This PR will be closed and archived after 14 additional days without activity.

We triage inactive PRs and issues in order to make it easier to find active work. If this PR should remain active or becomes active again, please reopen it. This PR was closed and archived because there has been no new activity in the 14 days since the inactive label was added.