Convert docs theme to minima and add template elements for baseline site #367
Conversation
Signed-off-by: Jeff Diecks <[email protected]>
There was a problem hiding this comment.
This looks pretty good overall. I think we'll want to include the Gemfile* ...files, though. We should also update the spellcheck config so it doesn't complain about the non-words that it's complaining about (I wish it were better about distinguishing things here, but alas)
Once we merge this, I'll need to update the release instructions to include modifying the current version to have the nav-title.
.gitignore
Outdated
| Gemfile | ||
| Gemfile.lock |
There was a problem hiding this comment.
Do we want to ignore these? Seems like it'd be beneficial for publishing (and for folks doing local builds, too)
There was a problem hiding this comment.
https://baseline.openssf.org/versions/2025-02-25#osps-qa-0201 suggests that we should probably have at least the Gemfile (and I'd recommend both)
There was a problem hiding this comment.
That's an interesting take... I don't read it that way. Since QA-02 is about "the software's direct dependencies," I wouldn't expect that dependencies for the documentation website would be covered by the test requirement.
There was a problem hiding this comment.
I agree that the docs website isn't strictly covered by QA-02, but the spirit of QA-02 applies. And, if nothing else, it makes life a lot more convenient for local builds, etc.
There was a problem hiding this comment.
If the output (released artifact) is the website, then the Jekyll configuration (and the go templating) are both the software used to produce the output. If that's not the intent, then we should figure out how to clarify.
On the other hand, the version of Jekyll used to generate the website is actually specified by https://github.com/ossf/security-baseline/blob/main/.github/workflows/web-publish.yml#L36, so maybe this is just "development cruft" that could be ignored as it only impacts contributors attempting to build a local copy.
We could spell-check only |
Co-authored-by: Ben Cotton <[email protected]> Signed-off-by: Eddie Knight <[email protected]>
| @@ -1,3 +1,7 @@ | |||
| --- | |||
| nav-title: Current Version | |||
There was a problem hiding this comment.
| nav-title: Current Version | |
| nav-title: 2025-02-25 (Current) |
There was a problem hiding this comment.
Not sure if the 2025-02-25 as the title in a navbar link is going to be very intuitive for someone who is new to the project
There was a problem hiding this comment.
I agree with Jeff. We could do "Current Version (2025-02-05)" instead, but I think for navbar purposes "Current version" is sufficient.
.gitignore
Outdated
| Gemfile | ||
| Gemfile.lock |
There was a problem hiding this comment.
https://baseline.openssf.org/versions/2025-02-25#osps-qa-0201 suggests that we should probably have at least the Gemfile (and I'd recommend both)
Can I get some help from someone on the spellcheck piece? I'm not familiar with cspell or how to configure it. |
Signed-off-by: Ben Cotton <[email protected]>
I just added commit 4661296 which fixes it. I went with a mixed approach here, and opted to forego the action-based config change so that it will work with local spell checking. Specifically, I excluded the Is it the best approach? Perhaps, perhaps not. |
Signed-off-by: Jeff Diecks <[email protected]>
|
OK PR uodated to add in the Gemfile and Gemfile.lock |
Signed-off-by: Travis Truman <[email protected]>
| <head> | ||
| <meta charset="UTF-8"> | ||
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
|
|
||
| {% seo %} | ||
| <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}"> | ||
| {% include head-custom.html %} | ||
| <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}"> |
There was a problem hiding this comment.
I don't see where custom-head.html is being included now?
Also, it looks like the previous stylesheet link had some cache-busting parameters for when the CSS was updated. I don't care strongly, but further updates to the CSS may take longer to show up (and I'm fine with that).
There was a problem hiding this comment.
i think you are right that custom-head.html is a legacy file from copying some things in from a setup of these templates elsewhere. we can probably do a follow-on issue to test removing that file and confirm nothing breaks.
| <!--[if lt IE 9]> | ||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script> | ||
| <![endif]--> |
There was a problem hiding this comment.
If you're running IE < 9.0, you're running a browser from 2009 or earlier, and it's even out of support on Windows Embedded POSReady 2009 with extended support updates. I think you can drop this.
There was a problem hiding this comment.
Yeah this came straight from the minima theme defaults, i'd be ok with us testing removal in a follow-on issue
| * https://fonts.google.com/specimen/Teko | ||
| - This *was* the recommended heading font, but is no longer. | ||
| Many found it hard to read. |
There was a problem hiding this comment.
We don't have this font -- remove this?
There was a problem hiding this comment.
Good catch, can remove this. @funnelfiasco let me know if you want me to do some more commits now to address some of these nits or if we want to followup with another PR later for cleanups.
There was a problem hiding this comment.
Might as well address them now, unless you want to juice your stats :-D
Resolves #341
Updates to Jekyll's default minima theme
Adds header and footer content to templates
Updates to OpenSSF brand guidelines fonts
adds front-matter to 3 of the markdown pages for navigation functionality
Corrects a minor grammar issue in index.md