Skip to content
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

Merged
merged 39 commits into from
Aug 20, 2024
Merged

Build a website. #4189

merged 39 commits into from
Aug 20, 2024

Conversation

jonmeow
Copy link
Contributor

@jonmeow jonmeow commented Aug 5, 2024

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.

@github-actions github-actions bot added documentation An issue or proposed change to our documentation explorer Action items related to Carbon explorer code labels Aug 5, 2024
@github-actions github-actions bot requested a review from zygoloid August 5, 2024 22:42
@github-actions github-actions bot requested a review from geoffromer August 5, 2024 22:42
@jonmeow jonmeow removed explorer Action items related to Carbon explorer code toolchain labels Aug 5, 2024
@jonmeow jonmeow removed the request for review from geoffromer August 5, 2024 23:08
@jonmeow
Copy link
Contributor Author

jonmeow commented Aug 5, 2024

NB, https://www.carbon-lang.dev/ should be configured, I think this will be effective once committed.

Copy link
Contributor

@zygoloid zygoloid left a 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.

.github/workflows/gh_pages_ci.yaml Show resolved Hide resolved
website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Show resolved Hide resolved
website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Show resolved Hide resolved
@zygoloid zygoloid requested a review from wolffg August 7, 2024 18:14
Copy link
Contributor Author

@jonmeow jonmeow left a 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.

website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Show resolved Hide resolved
website/prebuild.py Outdated Show resolved Hide resolved
website/prebuild.py Show resolved Hide resolved
@zygoloid
Copy link
Contributor

zygoloid commented Aug 8, 2024

Looks good to me, I also asked @wolffg to take a quick look.

@brymer-meneses
Copy link
Contributor

brymer-meneses commented Aug 8, 2024

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.

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.

@jonmeow
Copy link
Contributor Author

jonmeow commented Aug 8, 2024

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.

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.

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.

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.

@jonmeow
Copy link
Contributor Author

jonmeow commented Aug 16, 2024

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)

Copy link
Contributor

@chandlerc chandlerc left a 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.

Comment on lines 11 to 16
<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>
Copy link
Contributor

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...

Copy link
Contributor Author

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.

Copy link
Contributor Author

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.

# Exceptions. See /LICENSE for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

title: Carbon Language
Copy link
Contributor

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@p0358
Copy link

p0358 commented Aug 16, 2024

Thank you, the website appears way more readable now

@jonmeow jonmeow removed explorer Action items related to Carbon explorer code toolchain labels Aug 16, 2024
Copy link
Contributor

@chandlerc chandlerc left a 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?

Comment on lines +9 to +12
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`.
Copy link
Contributor

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...

Suggested change
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.

Copy link
Contributor Author

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.

Copy link
Contributor Author

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?

Copy link
Contributor

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.

website/_config.yml Outdated Show resolved Hide resolved
@jonmeow
Copy link
Contributor Author

jonmeow commented Aug 20, 2024

Generally, I think the code here is looking reasonable. Couple more suggestions inline.

Curious, should the URL be mentioned anywhere?

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.

@jonmeow
Copy link
Contributor Author

jonmeow commented Aug 20, 2024

Curious, should the URL be mentioned anywhere?

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.

@chandlerc
Copy link
Contributor

Curious, should the URL be mentioned anywhere?

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 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!

Copy link
Contributor

@chandlerc chandlerc left a 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.

Comment on lines +9 to +12
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`.
Copy link
Contributor

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.

@jonmeow jonmeow added this pull request to the merge queue Aug 20, 2024
Merged via the queue into carbon-language:trunk with commit b6396e9 Aug 20, 2024
8 checks passed
@jonmeow jonmeow deleted the pages branch August 20, 2024 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation An issue or proposed change to our documentation infrastructure
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants