-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Build a website. #4189
Build a website. #4189
Conversation
NB, https://www.carbon-lang.dev/ should be configured, I think this will be effective once committed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The mermaid diagrams are unreadable in dark theme. I wonder if there's some way we can theme mermaid so it uses better colors in dark theme. Alternatively, emlai's website had a light mode / dark mode toggle -- I wonder if we could add something similar easily. But I think this shouldn't be a blocking concern; we can iterate on this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note, also added some overflow-y css for the nav bar, which was bugging me.
Looks good to me, I also asked @wolffg to take a quick look. |
We can make use of something like vitepress to achieve this. It also uses markdown so there would be minimal configuration needed, but I'm not sure about the added complexity of Node and stuff. |
To be sure, in case you overlooked this in the PR description, I was having trouble getting emlai's website up-to-date for dependencies.
A quick look at vitepress (installing it, trying some configuration) suggests it's going to require work similar to Hugo/Docusaurus. If someone wants to pick up getting everything working great, let me know and I can set this PR aside. I'm just looking for something that looks good and is easy for me to maintain, without spending much more time on it. I'm seeing if we can have something simple for now, leaving more work for later. |
Note, I've done a few more edits to adjust text colors. I believe the css issues specific to the this change have been addressed. (Specifically, lighthouse complains about things, but not contrast) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Couple of small tweaks based on our discussion.
<footer class="site-footer"> | ||
This site uses | ||
<a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>. | ||
<br /> | ||
Hosted on GitHub Pages. | ||
</footer> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could we include copyright and license info here? seems like that would have it show up on every page. Unsure if there is a custom-footer option for the pages themselves...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's support for custom footers (https://just-the-docs.github.io/just-the-docs/docs/customization/#custom-footer). That could actually be used instead of this; I only put it here because of the default. I worry about making long footers though, I'll check with you separately about that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note, pushed with this, though still feels like a long footer to me.
website/_config.yml
Outdated
# Exceptions. See /LICENSE for license information. | ||
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception | ||
|
||
title: Carbon Language |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm guessing this is where the top-left corner "Carbon Language" comes from?
Wondering if we could say "Carbon Language Documentation" without it ruining the layout of the page... Or in some other way make it more clear that this isn't intended to be the long-term website for the project or language, but a build and render of our current documentation.
I can try getting this to render locally and play with some options if useful.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
Note, switched capitalization for https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings
Thank you, the website appears way more readable now |
Co-authored-by: Chandler Carruth <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Generally, I think the code here is looking reasonable. Couple more suggestions inline.
Curious, should the URL be mentioned anywhere?
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just hoping to document a bit the intended scope of the current effort, mostly to avoid confusion from external folks maybe looking at this part of the project...
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`. | |
Currently, the main website for Carbon is the GitHub project page as this | |
is still an experiment and in early stages of development. | |
However, we do maintain a documentation site where our project's documentation is rendered and more easily navigated. The documentation site 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`. |
Happy to iterate on better phrasing though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added a paragraph along these lines. Note though, I really want to keep the "how does this work" section focused on that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note, if there are more comments, maybe we could meet to run through details and get things resolved?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nope, this was one of the only comments I had, thanks.
If you mean "in general", I think we might want to add a link on GitHub once it's functional. (note there's a spot for this in the top right of https://github.com/carbon-language/carbon-lang/) If you mean "why doesn't the site have the FQDN in files", I think that's because in order to test webservers, you need relative links, without a FQDN. Bear in mind we aren't building a host, just the HTML. |
Maybe you mean "how is this configured"... added README notes, probably good to have written down. |
Yeah, this was basically what led to my question, and the docs make sense, thanks! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approving for leads, ship it and thanks.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nope, this was one of the only comments I had, thanks.
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. Theprebuild.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.