Docsy theme bug tracker

[zacharysarah]

This issue is a tracking thread for bugs with the application of the Docsy Hugo theme to the website.

Preview URL: https://kubernetes-hugo-staging.netlify.com/docs/home/

UPDATE, 30 April 2020: All sections of the preview URL are ready for testing.

• Before reporting a bug, please check to see if it's already reported.
• Please comment on this issue with any formatting or navigation bugs you discover.

[zacharysarah]

Language and version selectors don't work.

[gochist]

Currently on the master's website, if there is an unlocalized document, a link to the upstream document is provided in the menu on the left sidebar. But on the hugo staging website, it is not provided.

For example on master: https://kubernetes.io/ko/docs/tasks/

[pjhwa]

There is a typo for the youtube link in the footer like the below: https://youtbue.com/kubernetescommunity

[pjhwa]

There are broken links at the bottom of every documents like the below:

For example: https://kubernetes-hugo-staging.netlify.app/docs/setup/learning-environment/minikube/ At the bottom: Last modified March 30, 2020: content/en migrated from current master (36b21b7)

[zacharysarah]

Version selector is outdated.

• Versions 1.17, 1.18 are missing.

[zacharysarah]

Language selector is outdated:

• Norwegian is enabled. (It shouldn't be.)
• Polish, Ukrainian are missing.

[zacharysarah]

Given how outdated the preview code appears, a merge PR is likely to generate a significant number of merge conflicts.

[sftim]

Given how outdated the preview code appears

(from https://github.com/kubernetes/website/issues/20344#issuecomment-622221744) I can help with a rebase, or even create my own PR that cherry-picks just the Docsy changes.

[sftim]

https://kubernetes-hugo-staging.netlify.app/docs/concepts/ seems harder to navigate on mobile than I'd expect. It turns out that's because there are 2 hamburger icons and one of them is hidden with a narrow viewport.

Examples (narrow viewport first; notice how the hamburger is actually extending right of the viewport)

 

[sftim]

The existing site has an icon you can click to copy a {{< codenew >}} block to the clipboard. The docsy site does not offer that behavior, AFAICT.

[sftim]

The version selector issue mentioned in https://github.com/kubernetes/website/issues/20344#issuecomment-622220569 looks partially fixed; however, the page at https://kubernetes-hugo-staging.netlify.app/case-studies/ does not have a working version selector.

[sftim]

Notes are blue in the existing docs but orange in the revised docs. I think it makes sense to have notes be blue and reserve orange for caution blocks. At the moment the Docsy site does not distinguish those blocks by color.

[sftim]

nit: The feature state shortcode renders the Kubernetes version as <code> and because of the revised styling also colors the text. I would render the “Kubernetes 1.18” (etc) part with black text.

[sftim]

nit: tab header styling looks odd (the skeuomorphism of file tabs isn't as obvious compared to the existing site) eg https://kubernetes-hugo-staging.netlify.app/docs/contribute/style/hugo-shortcodes/#tabs-demo-code-highlighting

[kbhawkey]

Looks like we are back to generating .scss files and committing the changes. Docsy uses PostCSS (from the docsy docs),

To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install

[sftim]

Following on from https://github.com/kubernetes/website/issues/20344#issuecomment-623548180

Any way we can have the static site build do that generation?

It might mean that people contributing to docs have to add extra dependencies or switch to using a container-based local preview. (Given what Kubernetes is about, I'm fine with nudging people towards using containers).

[sftim]

~The existing site offers readers the chance to subscribe by email to KubeWeekly. The Docsy equivalent doesn't seem to offer this anywhere.~

[sftim]

not-yet-localized pages are missing (reported in #19309)

[sftim]

no placeholder text for search if viewport narrow (reported in #19308)

[kbhawkey]

The existing site offers readers the chance to subscribe by email to KubeWeekly. The Docsy equivalent doesn't seem to offer this anywhere.

I see the option from the k8s home page. Would be nice if the KubeWeekly text provided a link to the newsletter (online)?

[sftim]

Case studies logo backgrounds don't match page body (reported in #20760)

[kbhawkey]

Page: https://kubernetes-hugo-staging.netlify.app/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/

Blend background color (no gray)?

[kbhawkey]

Some of the images are not displaying on https://kubernetes-hugo-staging.netlify.app/. This is a former bug that may be fixed when the docs source/templates are updated.

[mrbobbytables]

I noticed a few things:

• The icons/menu on the right don't look quite right, I think the icons are suppose to be next to the names instead of above them (link):

• We may need to rethink how blog pages are organized / presented -- the view of the left hand menu is kind of messy (link):

Low hanging fruit thing, but the calendar that is linked to doesn't really contain much / pretty sparse, like it still has kubecon as last month. I don't know who manages it 😬

[zacharysarah]

@mrbobbytables The preview link is based on a seriously outdated branch. To test what it looks like right now, we need to merge #20874 and the PRs on which it depends. I'd hold off on further review until we merge #20874. Thanks for taking the time to review! 👍

[zacharysarah]

@sftim @gochist @kbhawkey @mrbobbytables and everyone:

As an update: we now have a PR (#20874) based on the current version of master. Much of the feedback here is either resolved by rebasing, or specific to Docsy as a theme rather than Gearbox's implementation of it.

In order to keep feedback relevant and collected in a single source, I'm going to close this issue and recommend we give feedback on #20874.

/close

[k8s-ci-robot]

@zacharysarah: Closing this issue.

In response to [this](https://github.com/kubernetes/website/issues/20344#issuecomment-628404977): >@sftim @gochist @kbhawkey @mrbobbytables and everyone: > >As an update: we now have a PR (#20874) based on the current version of `master`. Much of the feedback here is either resolved by rebasing, or specific to Docsy as a theme rather than Gearbox's implementation of it. > >In order to keep feedback relevant and collected in a single source, I'm going to close this issue and recommend we give feedback on #20874. > >/close Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.