knative/website

Hugo templates for the Knative website.

website's Issues

Document the knative.dev maintainer instructions

Need to capture the process and steps for how to maintain the knative.dev website at knative.dev

• Why and how to keep the Staging branch in sync: https://github.com/knative/website/tree/staging
• Docsy - Keeping our theme up to date: https://www.docsy.dev/docs/updating/
• Netlify auto PR builds: https://app.netlify.com/sites/knative/deploys
• Hugo + limitations: No nested shortcodes

Code Copy Buttons

Is it possible to have code copying buttons so that copying code from quick-start guides and tutorials is easier? I think the more technical term for that is 'code highlighting', but regardless, it would make code transfer faster in some of the tutorials.

Investigate tools for auto changelog generation

Look into how to automatically summarize change for a release in the knative/docs repo.

Potential option(s):

• https://github.com/github-changelog-generator/github-changelog-generator was suggested by a peer OSS project

cc/ @eallred-google @samodell

Need custom 404 page to redirect to knative.dev

For pages or content that get deleted from a new release, we should have a 404 page to explain that users can look in an archived branch for deleted content.

Search results include advertisements

When we do a search, ads for related terms appear on the search page. We should be able to opt out of those.

https://www.knative.dev/search/?q=testing

Support deep-linking to tabs

From @mattmoor

One thing I do NOT like about the tabs is that I cannot deep-link an optional install guide

Enable and then add (or replace) line highlighting for code syntax

https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences

With Hugo 0.60.x you can specify which lines in a code block that you want highlighted (for example to show/demonstrate how and where to add an element in a config file).

If you add hl_lines (ie. hl_lines=8 15-17), the specified line numbers get yellow highlighting.

Nice to have for our readfile shortcode

Unable to create permanent link to docs for latest Knative release

Today https://www.knative.dev/docs/ points to docs for the 0.4 releases of Knative. Soon that same URL will point to 0.5. What I'd like to be able to do is create a permanent link to the docs for any specific Knative version, even the most recent release.

I can create a permanent link for older docs, like the 0.3 release, as the URL looks like https://www.knative.dev/v0.3-docs/

But for the current release the URL does not have the version number and thus I can't create a permanent link to docs for that version. Nor does manually typing in https://www.knative.dev/v0.4-docs/ work until v0.4 is no longer the current release.

Add how-to-use documentation for Tabs shortcodes, similar to Readfile shortcode

All other shortcodes have a comment explaining how the shortcode works and how to use it.

For example, https://github.com/knative/website/blob/master/layouts/shortcodes/readfile.md

The Tab.html and Tabs.html should also have comments about how they work and how to use them.

Investigate nested shortcodes (how to use .Parent variables)

A PR from last Oct added this to the Hugo docs: https://gohugo.io/content-management/shortcodes/#nested-shortcodes

"You can call shortcodes within other shortcodes by creating your own templates that leverage the .Parent variable. .Parent allows you to check the context in which the shortcode is being called."

The example: https://gohugo.io/templates/shortcode-templates/#nested-shortcode-image-gallery

Action: Look into whether this fixes the issues with using our readfile shortcode to add README files (today, any shortcodes in the README.md files simply render the shortcode as text and fails to process the shortcode - for example dynamically add version numbers or branch names

Click to open code sample button

Update the existing readfile shortcode to include a button that opens the code sample in new window.

Make search results filter by version

With multiple versions, results from a search within knative.dev include several similar or complete duplicates of a single topic.

• Filter content by release version (Refining searches, more about refinements)
• DONE: We also need to be able to filter out the "development" content (master branch).

Merge top level "Contributing" into a subsection in "Community"

To align with community views, we should merge both the "community" and "contributing" sections in the website into just "Community".

There should be clear sections within "Community":

• Learning, discussion groups, help resources
• Contributor Guidelines (currently all under the "contributing" section)
• Community contributed and owned code samples

Add editable search box to search results page

Describe the change you'd like to see
From this page: https://knative.dev/docs/
if I enter a search phrase I get a new tab/window with the results.
However, the search phrase is not shown to me on that results page in an editable form. Which means if I had a typo in my search I need to close the window and use the old/previous window. It would be nice if I could just edit the search phrase on this new results page.

Here's what the page looks like now:

Investigate the use of container images

https://hub.docker.com/r/klakegg/hugo

From an issue in Docsy:

version: '3.6'
services:
  web:
    image: klakegg/hugo:0.64.0
    command: server
    volumes:
      - .:/src
    ports:
      - 1313:1313

Add byline to the blog

What is changing? (Please include as many details as possible.)

We are adding a static information field to blog entries on Knative.dev

How will this impact our users?

Users will be able to know who is writing stories and can contact them if they need; Knative contributors can get more recognition for their work

In what release will this take happen (to the best of your knowledge)?

N/A
ASAP

Context

Link to associated PRs or issues from other repos here.

1. Discussion at the last Knative documentation working group

@evankanderson @carieshmarie @isdal

site_cookie is only valid for 7 days

When accepting the site_cookie, its epxires within ~ 7 days. I just cleared the cookie and reaccepted it, but got this expiry datum:

I've seen in the code that it sets the expiry to 365 days, but this doesn't seem to work.

I'm located in Europe (GMT+2) (as cookie-consent.js makes a difference between Europe and the rest of the world)

Add a webhook to the knative/community for auto builds

Investigate whether its necessary to connect knative/community to the docs builds in netlify (auto rebuild for merged content?). The alternative is to manually kick off a build.

all quotation mark was rendered as html code

Use Knative to host the Knative website

I spent a little spare time over the weekend looking at containerizing the Knative website so that it could be run on a Knative-compatible host. Turns out it wasn't that hard to move everything into a two-stage docker build flow.

I haven't moved all of the configuration in the current build script, e.g. supporting PRs.

I've pushed these changes to a fork of this repo, here: https://github.com/rgregg/website/tree/self-hosted, and you can see an example of it running here on Cloud Run: https://knative-website-7jeitjla7a-uc.a.run.app/

I'd love to see us start to dogfood Knative to run our own website. What do other folks think?

Another advantage of this approach is that local-development is super easy, since the whole build and run environment happens inside a container. You don't need to setup any build environment on your local machine, just clone the repo and go. This is a big improvement over getting the build environment setup on your own machine!

Another big advantage is that we can control more of the process. We're not subjected to Netlify changing the version of Hugo we're using under our nose, potentially breaking how our text is rendered.

If this is interesting, I'm happy to keep working on getting the full set of functionality ported over.

tabs and preformatted blocks have different widths

If you look at the width of the tab and the preformatted block inside and outside of the tab, the borders all show at different widths. This issue tracks bringing some consistency to that.

cc @lionelvillard for CSS wisdom 🙏

slack.knative.dev is 404

The vanity URL slack.knative.dev no longer works (redirects to this non functioning "join Knative" link: https://join.slack.com/t/knative/shared_invite/enQtNDA1ODA1MTc2NjE1LTA3ODU5ZDlmMTg2N2MzMGI2NDc0YzkxMTg5MWRhNmZlYjgwMTM2NzE3ZThkYzgzMjE5ZTExYTMwMmEyZjk5ZTQ&usg=AOvVaw0A2SyTvfGCJV-cIeF5kLiK).
That vanity link is everywhere and currently displays a "This link is no longer active" page.
This issue was reported in the #docs channel regarding the site footer link but given that the vanity URL is everywhere (blogs, other product referral links, etc), is there another Slack join link that we can use to update the vanity URL redirect?

An alternative is to use: https://knative.slack.com/signup#/
But that page limits joining to only three domains:

Take a step towards improved SEO with synonyms

We can add synonyms to our search settings in addition to good titles, filenames, and time (the more that users click and navigate to our site and specific pages, we will eventually climb higher up in the results).

Details here: https://support.google.com/customsearch/answer/4542403

What are the industry terms being used that we can associate with our Knative terms and language?

Add here, ping, or email me some terms and their associated Knative terms, that you want me to add.

Improve Nav menu behavior

Add click to close nav section:

Allow users to click on a menu section (ie. a topic in the menu that include child nodes) to not only open but also close. For sections with lots of child nodes that span the whole screen, its better (expected) behavior to click once more to close that really long section (to view the contents that gets pushed off the screen).

Investigate Istio CSS: https://istio.io/docs/
(They use icons to indicate a "section", which you can click to open/close those sub-trees)

Investigate Link Checking

Some suggested link checkers (from other peer OSS projects):

• https://github.com/wjdp/htmltest
• https://github.com/raviqqe/muffet

Ideally, this is done across the whole site and also with a linter before a PR gets merged (to enable authors and prevent 404s from even happening).

Background: knative/docs#772

Reduce the amount of one-shot shell scripting during development

It would be nice to be able to use symlinks and hugo's ability to reload dynamic files during development, rather than needing to re-run localbuild.sh.

This produces three benefits:

• The golang is probably more approachable for many developers, especially as the find commands become more complex.
• The golang templates are applied when the content is rendered, which reduces the risk of corrupting static files, since they won't be rendered through the template.
• When complete, it should be possible to use a static docker image with the website and map the "docs" directory into it for live iteration using the actual website rendering.

Feature State shortcode

It would be useful to have a featurestate shortcode akin to: https://kubernetes.io/docs/contribute/style/hugo-shortcodes/#feature-state-code

Investigate Hugo v0.60.x for knative.dev

Hugo now uses goldmark as default markdown renderer in the latest version of Hugo. Preliminary test show that it resolves the issues captured in knative/docs#1202 (nested lists and codeblocks render out of order and incorrectly indented while GitHub renders the markdown without error).

There are some breaking changes noted but its unclear what the impact is to knative.dev

New markdown processor support by Hugo:
https://gohugo.io/content-management/formats/#list-of-content-formats

How to configure: https://gohugo.io/getting-started/configuration-markup/

Content rendering is hiding the title and first lines

See https://knative.dev/contributing/mechanics/feature-tracks/ for an example.

Tabbed content in single page? Like cloud.google.com?

For content that only differs by programming language (ie. Hello World code samples), can we use the readfile shortcode to mimic the c.g.c site behavior where a single page houses multiple tabs that each contain different content?

cc/ @matzew

Remove build docs from Knative website

related: knative/docs#1475

shortcodes with HTML in {{< tab >}} are stripped

So I hit this trying to use #126 from within a tab...

Basically, unless I flip the switch to allow HTML through from markdown (even though the HTML is coming from a shortcode!) the HTML generated by my feature-state is scrubbed 😢

I suspect that this is a problem with tab, not the new stuff, but I don't speak this stuff well enough to meaningfully debug (it's all trial and error).

cc @RichieEscarez in case he has any quick insights 🙏

Need to update the GitHub link logic because its under Community

In the file below, the logic needs to point to knative/community for all but the code samples under the "Community" section on knative.dev

https://github.com/knative/website/blob/master/layouts/partials/page-meta-links.html#L49

Since Contributing was merged under Community, this condition no longer works:
{{ if eq $pageSection "contributing" }}

Release Artifact shortcode

Today we embed {{< version >}} into URLs to synthesize release URLs.

This doesn't really work for the pre-release docs, which would ideally reference nightly builds 👌

What if we had a shortcode that could produce the appropriate artifact path based on version?

e.g. {{< artifact repo="serving" name="serving-core.yaml" >}}

Add knative/community URL handling

Viewing from GitHub repo shows broken links for community content.

We should update the script to convert fully qualified URLs into knative.dev relative URLs.

For example:

(support linking in GitHub)
https://github.com/knative/community/blob/master/CONTRIBUTING.md

(convert to relative link for website)
contributing/contributing

Improve CSS for knative.dev to use our brand colors

The landing page for knative.dev is using the default CSS for the template right now, with a few tweaks that Richie has put in there.

I'm opening this issue to track updating the CSS to have a more polished landing page.

Track use cases for vendor-specific blogs

In this issue, @abrennan89 and I are tracking implementation scenarios to create a specific blog template in the blogging guidelines I'm working on.

Top page is hard to read on mobile

Top page is hard to read on mobile due to too broad margin on both sides.

e.g., on iPhone SE:

Repeated release labels shown on website

There are two release v0.12 labels in release selection.

Releated issue: knative/docs#2328

Website should pull community content from knative/community instead of knative/docs

I've just created the new knative/community repo to hold our governance and community docs and copied the content from the docs repo.

However, I can't remove the content from docs until we have the website setup to pull in the content from the new repo. Looks like we need to update the build script to clone the latest content from that repo into the content folder as part of the pre-hugo steps.

Navigation bar should say "docs" not "release: latest"

The navigation bar, especially on www.knative.dev, doesn't have an entry for Docs, it just has a drop down to select the version.

On the landing page/non-docs pages, it should say "Docs" and take you to the latest release when you click on that.

On docs pages, it could either say the same and we move the version selector somewhere else (right column) or we could keep it in the navigation bar.

Update Hugo version (which updates Go)

I found that by updating Hugo to 0.56.0 we can resolve some of the odd rendering on knative.dev around nested lists and codeblocks.

Edit page button on a specific release doesn't take you to the right place

If you're viewing an older release, like 0.3, and click the Edit Page button, it takes you to an invalid URL.

This repo needs a DEVELOPMENT.md

How do I test changes here (perhaps in concert with docs) locally (or remotely!)?

/assign @samodell

Add social image preview to knative.dev

Copied from the Docs repo: knative/docs#1696

From @steren :

When I share https://knative.dev/ on Twitter, no image thumbnail appears in the twitter card.
You can test this at https://cards-dev.twitter.com/validator

How to fix:

Add the appropriate tags so that Twitter and other social networks pick up the Knative logo as thumbnail as well as a nice summary

Fix "Edit this page" and "Create issue" buttons for knative/community

With the content for all contributor and governance that now lives in knative/community, the right side content bar with the auto generate edit this page and create issue need to be update to point to the new repo.

Need to add logic to look for the "contributing" section and then build the links to point to the knative/community repo in this file

Docs version switcher uses both "development" and "Pre-release"

In the dropdown of the version switcher, it lists "development" to see in-progress docs for the upcoming release. But, if you choose that version, the title of that same version switcher says "Pre-release". Should we choose just one of those terms and use it consistently in the version switcher?

Add borders to tables

Content in tables is easier to read when there are borders.

For an example of a table in our docs, see: https://www.knative.dev/docs/serving/samples/

On GitHub, the table displays with a simple border that makes it more readable: https://github.com/knative/docs/tree/master/docs/serving/samples

improve webdev and pagespeed scores

Google's public website measurement tools indicate that knative.dev and the pages on that site could use some improvements.

https://web.dev/measure/
https://developers.google.com/speed/pagespeed/insights/?url=knative.dev&tab=mobile
https://developers.google.com/speed/pagespeed/insights/?url=knative.dev&tab=desktop
https://www.thinkwithgoogle.com/feature/testmysite/
testmysite report: https://storage.googleapis.com/gweb-mobile-hub-test-my-site.appspot.com/public/reports/efd38062ead9419386ce04fdcfc45461.pdf

I mainly looked at the homepage, but testmysite averages across the whole domain. I'm guessing we use some shared css etc across the whole site, and that fixing the homepage will improve most/all other pages as well, but others should be checked too.

Possibly of interest: https://developers.google.com/speed/

Sounds like the current best tool from Google is https://web.dev/vitals/

https://webmasters.googleblog.com/2020/05/evaluating-page-experience.html

Forked from knative/docs#2526

Other site related issues that were opened in the knative/docs repo

https://github.com/knative/docs/projects/19