New Kubeapps website #4705

antgamdia · 2022-05-13T10:55:47Z

Description of the change

This (big) PR is adding the new Kubeapps website source in our repo. It is based upon the VMware open-source project template, but have been adapted to our needs.
Under the hood, it is using Hugo (the instructions to build/run locally the website are in the readme file) for generating the static files and Netlify to deploy it (not public yet, see #3953)

More details: inline

Benefits

A brand new Kubeapps website!

Possible drawbacks

Broken links to files

Applicable issues

related New Kubeapps web #3953

Additional information

Known broken links (10 broken out of 777):

---- Images (due to how deep they are)
--> FIXED! Some files have been moved so that the images get properly rendered

--- links under /docs/latest/project/...
--> FIXED! Even if they are symlinks and we can't modify the project files, we can add a workaround in the code in charge of rendering the links. Having applied this fix results in no more broken links! 

--- Every non-md file
--> FIXED! We have replaced the relative link with the link to the main branch in github. Whereas it is not 100% compatible with multiple versions, at least, links get rendered. 

--- Links to folders
--> FIXED! Idem, using a link to github instead. Same tradeoffs.

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Signed-off-by: ppbaena <ppbaena@gmail.com>

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com> Conflicts: docs/background/update-api-docs.md site/content/docs/latest/background/update-api-docs.md

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

netlify · 2022-05-13T10:55:54Z

✅ Deploy Preview for kubeapps-dev ready!

Name	Link
🔨 Latest commit	`cab62f3`
🔍 Latest deploy log	https://app.netlify.com/sites/kubeapps-dev/deploys/6282646eb412f00008db1526
😎 Deploy Preview	https://deploy-preview-4705--kubeapps-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia · 2022-05-13T11:33:42Z

docs/README.md

-| [How-to guides](./howto/)   | They guide you through the steps involved in addressing key problems and use-cases.      |
-| [Background](./background/) | Dive into the overall architecture and implementation details of Kubeapps.               |
-| [Reference](./reference/)   | Technical information - developer guides, design proposals, examples, translations, etc. |
+The documentation files have moved to [/site/content/docs/latest](/site/content/docs/latest).


Big downside... docs have to be under the hugo site subfolder in order to get them rendered :( That's why I'm moving the docks down there.
Good news is that we will get pretty URLs like: /docs/latest/howto/oidc/azure-active-directory/ based on the md's name

They can't be symlinked like you've done for other files? (Might not be the best solution, as then relative refs to other static content might be painful, just wondering).

I've tried to create a symlink to the folder but it didn't work in GitHub: it rendered as a text file with a link to the symlinked folder :(
However, instead of just saying "ey, we have moved it", we can leave the links to the howtos, background, refs, so that users can click on them and get redirected to the proper file. I'll do that.

Oh - I actually meant whether it was possible the other way around - leave the docs where they are currently, and symlink to them from the hugo content source. But yep, guessing. you've tried all the options.

And, I think it's fine having them in ./site/content/ anyway. Although, why are is the docs/latest/ needed? Aren't the docs in our main branch always going to be the latest? (ie. why have you not used site/content/tutorials/getting-started.md rather than site/content/docs/latest/tutorials/getting-started.md? - I assume there's a good reason, just keen to understand). I assume the latest is so we can have multiple versions in our one main branch so hugo can render docs for multiple versions at once? And I assume the extra docs is so we can have ./site/content/static/ etc. as well. Just wondering if there might be a simpler structure to achieve those (particularly the first, whether we could have just one copy of the site in the branch - not sure).

Yep, it would have been easier if it wasn't for the template. It is prepared to host several docs versions or, if there is only one, it gets served under latest. The template has some parameters for handling that and the whole template is prepared for that. I didn't want to diverge that much from the official template, so that's why I left the core structure.
Anyway, happy to change it in a follow-up PR.

Oh - it's a constraint of the template... yeah, I agree, let's stick to the template :)

antgamdia · 2022-05-13T11:35:42Z

site/README.md

+
+## Check writing
+
+In order to validate and ensure a proper style of writing, it is recommended to run the [vale validator](https://vale.sh/docs/vale-cli/installation/) with a set of [style rules](https://github.com/errata-ai/styles). The rules are present in the project codebase in the directory. Some of them have been slightly modified to fit our project needs.


The rules have been added to the repo, under the folder styles

Excellent. Assuming people can add exceptions intentionally if needed, it'd be great to have the build fail if the validator picks a breach of the style rules?

Well... there are plenty of pre-defined warnings and errors. I have disabled some of them, but others remain as is. If we happen to add it to the building process, certainly we can tweak the rules and determine which are errors vs warnings for us.
Unfortunately, AFAIK, there is no way to set sth as an exception, but we can convert it into a warning.

Here's a example of the output:

content\docs\latest\tutorials\using-an-OIDC-provider.md 1:1 warning Try to keep the Flesch reading Readability.FleschReadingEase ease score (39.42) above 40 (college). 3:28 error Using 'simple' may come across alex.Condescending as condescending. 14:1 error Don't start a sentence with write-good.ThereIs 'There are'. 48:1 error Don't start a sentence with write-good.ThereIs 'There are'. content\docs\latest\tutorials\managing-carvel-packages.md 89:128 error Don't start a sentence with write-good.ThereIs 'There are'. 215:45 error Using 'easily' may come across alex.Condescending as condescending.

For instance, with this report I would try to reduce the complexity of the sentences in using-an-OIDC-provider.md and rephrase some sentences to remove, if possible, some easily and simple words. However, I don't see it is really a problem to start with there are..... Perhaps I'd remove that rule or, at least, mark it as a warning, not an error

antgamdia · 2022-05-13T11:36:38Z

site/config.yaml

+  docs_search: false
+  docs_search_api_key: api_key
+  docs_search_index_name: index_name
+  docs_versioning: true


The search feature is pending, as we will use an external indexing system that requires us to be "production ready" first.

antgamdia · 2022-05-13T11:37:03Z

site/config.yaml

+  github_url: "https://github.com/vmware-tanzu/kubeapps/"
+  googleSiteVerification: xxxx
+  gtmId: UA-1874455-13
+  oneTrustId: 3b23306b-6d55-4552-bcf0-1c1276db55e9-test


Configuring oneTrustId is pending as well

antgamdia · 2022-05-13T11:38:37Z

site/content/community/_index.html

+      </div>
+      <div class="content">
+        <h3>
+          <a target="_blank" rel="noopener" href="https://github.com/vmware-tanzu/kubeapps/"


The templating {{ params.xxxx }} don't work here, it would have to be a partial not a content, but the template was this way. Let's change in the future maybe.

antgamdia · 2022-05-13T11:44:16Z

site/content/docs/latest/howto/private-app-repository.md

@@ -27,8 +27,8 @@ or to allow other users the ability to deploy charts from App Repositories in a

 When creating an AppRepository in Kubeapps, you can now additionally choose (or create) an [imagePullSecret](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) to be associated with the AppRepository:

-<img src="../img/app-repo-pull-secret.png" alt="AppRepository with imagePullSecret" width="600px">
-<img src="../img/app-repo-pull-secret-2.png" alt="AppRepository with imagePullSecret" width="600px">
+![AppRepository with imagePullSecret](../img/app-repo-pull-secret.png)


Required for displaying the imgs

antgamdia · 2022-05-13T11:45:47Z

site/content/docs/latest/project/.placeholder

@@ -0,0 +1,11 @@
+This directory is expected to contain symlinks to certain files of the root project directory. This way, these files will be rendered in Hugo.


As we can't add external (not in the hugo folder) files for them to be rendered as normal files, we need to create a symlink so that they get "virtually" into the website folder.

antgamdia · 2022-05-13T11:46:09Z

site/content/docs/latest/reference/design-proposals/README.md

@@ -12,7 +12,6 @@ This folder contains documents/links used to design new features for Kubeapps.
  - [Simpler deployments](./dashboard/deployment-improvements.md)
  - [Improve UX in application view](./dashboard/application-view-revamp.md)
  - [Upgrade to Clarity design](./clarity-ui.md)
- [Notify Available Chart Updates](https://docs.google.com/document/d/1oG9nerd5CurWSIwH33kKCsOCtkSFMgcm8SuTJyuSnxs/)


Broken link

antgamdia · 2022-05-13T11:48:02Z

site/data/docs/latest-toc.yml

@@ -0,0 +1,93 @@
+toc:


The menu is manual, so we would need to add new featured documentation items by hand.

antgamdia · 2022-05-13T11:48:50Z

site/netlify.toml

+to = "/404/"
+status = 404
+
+# [[headers]]


Not sure if it is required, but I left it here until we add the search feature

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

castelblanque · 2022-05-13T13:45:03Z

This is cool! Great job, and awesome that preview comment from the bot 😄

Make them point to github instead Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia · 2022-05-13T15:25:40Z

Here's a summary of the broken links so far:

Links referenced from the project files

https://kubeapps-dev.netlify.app/docs/latest/project/CODE_OF_CONDUCT.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/contributing/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/tutorials/using-an-OIDC-provider.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/howto/OIDC/using-an-OIDC-provider-with-pinniped.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/howto/access-control.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/tutorials/getting-started.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/chart/kubeapps/README.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/howto/dashboard.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/tutorials/kubeapps-on-tkg/README.md<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/values.yaml<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/chart-readme/ and 1 more

https://kubeapps-dev.netlify.app/docs/latest/project/docs/reference/design-proposals<a href>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/project/governance/ and 1 more

Links broken images (update: fixed!)


https://kubeapps-dev.netlify.app/img/design-proposals/overview.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/error-handling/error-handling/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/deployment-form-basic.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/deployment-improvements/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/deployment-form-adv.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/deployment-improvements/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/chart-dependencies.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/pod-count.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/credentials-box.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/configuration-options.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/url-list.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/resources-table.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

https://kubeapps-dev.netlify.app/docs/img/dashboard/appview-revamp.png<img src>
Linked from: https://kubeapps-dev.netlify.app/docs/latest/reference/design-proposals/dashboard/application-view-revamp/ and 1 more

absoludity · 2022-05-16T01:15:31Z

Excellent work Antonio. Love the preview per branch that the netlify bot provides, very handy.

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia · 2022-05-16T14:58:55Z

site/themes/template/layouts/_default/_markup/render-link.html

+    <!-- BEGIN Workaround to render the links of the symlinked files  -->
+    {{- if in .Page.RelPermalink "/docs/latest/project/" }}
+        <!-- Replace the links pointing to the project files with the proper link -->
+        {{- if in .Destination "/docs/" }}
+            {{ $link = printf "../../../../%s" (replace (replace (replace (replace .Destination "docs/" "docs/latest/") ".md" "") "/README" "") "_" "-" | lower ) }}
+        {{- end }}
+        <!-- Replace the chart/kubeapps/readme links with the proper link -->
+        {{- if in .Destination "/chart/kubeapps/" }}
+            {{ $link = printf "../%s" (replace (replace (replace .Destination "/chart/kubeapps/" "/chart-readme/") ".md" "") "/README" "" | lower ) }}
+        {{- end }}
+        <!-- Replace "_" with "-"" -->
+        <!-- If we start having issues with it, just apply the substitution if destination is "CODE_OF_CONDUCT" -->
+        {{- if in .Destination "_" }}
+            {{ $link = printf "../%s" (replace (replace $link "_" "-") ".md" "" | lower ) }}
+        {{- end }}
+    {{- end }}
+    <!-- END  -->


This is the workaround to replace some parts of a link's href so that it points to the proper place when becoming rendered in a symlinked file.
With this patch, every link is working!

ppbaena

+1

antgamdia and others added 30 commits May 10, 2022 17:05

Add site template and boilerplate

2e06374

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Single version docs

d72464f

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

wip index

e414090

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

add community page

54b0746

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Remove blog

89120df

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add resources section

32e01b7

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

wip add docs

9cbc465

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

fix some links

4876594

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add netlify

df52fe5

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix base url

b15fe2d

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix team metadata

813c6e5

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix team metadata

1e2b69a

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Move docs to the site folder

2054605

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix broken link

8457a71

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Manifests folder moved to reference

788049b

Signed-off-by: ppbaena <ppbaena@gmail.com>

Move imgs in docs

195d87e

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Ignore files

8bcbff3

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix readme files

426fb42

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix manifest uris

78b3a9a

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add minor fixes in docs

270842b

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add style rules

40d67c0

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add instructions

4b3449a

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix some broken links

d32be89

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Autofix markdown issues

4d2d1e6

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Update README.md

609aeaf

Add symlinks

92cd25f

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix image rendering

4d3a1c2

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Merge branch 'main'

2c7c4cb

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com> Conflicts: docs/background/update-api-docs.md site/content/docs/latest/background/update-api-docs.md

Bring file deleted after merge back

ce5fea8

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Replace ’ with '

cec6a38

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia added 2 commits May 13, 2022 13:24

Fix gitignore

29ac0cd

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix quotation marks

25e759d

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia commented May 13, 2022

View reviewed changes

antgamdia added 3 commits May 13, 2022 14:49

Fix broken links

ef2cbca

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Merge branch 'main' into site-new

da2760b

Fix broken links

98e9bc0

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia added 2 commits May 13, 2022 17:05

Fix links to external files

753b3f7

Make them point to github instead Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix minor typos in links

c1ea571

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia added 3 commits May 16, 2022 10:07

Run prettier

099e352

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Add links to the new docs in the docs/readme file

7d2e675

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix link

caa2455

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia marked this pull request as ready for review May 16, 2022 09:08

antgamdia added 8 commits May 16, 2022 12:47

Update external links

d028e6e

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Use https urls when possible

80ac2ca

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Fix links pointing to howto/reference

d7bf1af

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Move some files to avoid broken img links

99e31ae

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Improve report issue link

e000080

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Workaround to fix project's links

b89a44e

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Apply link workaround only in remote links

b3298f1

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

Tweak the render-link to fix more broken links

cab62f3

Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>

antgamdia commented May 16, 2022

View reviewed changes

This was referenced May 16, 2022

Rename site-new with main #4715

Merged

New Kubeapps web #3953

Closed

ppbaena approved these changes May 17, 2022

View reviewed changes

antgamdia merged commit 8cd7116 into main May 17, 2022

antgamdia deleted the site-new branch May 17, 2022 08:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Kubeapps website #4705

New Kubeapps website #4705

antgamdia commented May 13, 2022 •

edited

Loading

netlify bot commented May 13, 2022 •

edited

Loading

antgamdia May 13, 2022

absoludity May 16, 2022

antgamdia May 16, 2022

absoludity May 16, 2022

absoludity May 17, 2022

antgamdia May 17, 2022

absoludity May 18, 2022

antgamdia May 13, 2022

absoludity May 16, 2022

antgamdia May 16, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

antgamdia May 13, 2022

castelblanque commented May 13, 2022

antgamdia commented May 13, 2022 •

edited

Loading

absoludity commented May 16, 2022

antgamdia May 16, 2022

ppbaena left a comment


		## Check writing

		In order to validate and ensure a proper style of writing, it is recommended to run the [vale validator](https://vale.sh/docs/vale-cli/installation/) with a set of [style rules](https://github.com/errata-ai/styles). The rules are present in the project codebase in the directory. Some of them have been slightly modified to fit our project needs.

		@@ -0,0 +1,11 @@
		This directory is expected to contain symlinks to certain files of the root project directory. This way, these files will be rendered in Hugo.

New Kubeapps website #4705

New Kubeapps website #4705

Conversation

antgamdia commented May 13, 2022 • edited Loading

Description of the change

Benefits

Possible drawbacks

Applicable issues

Additional information

netlify bot commented May 13, 2022 • edited Loading

✅ Deploy Preview for kubeapps-dev ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

castelblanque commented May 13, 2022

antgamdia commented May 13, 2022 • edited Loading

absoludity commented May 16, 2022

Choose a reason for hiding this comment

ppbaena left a comment

Choose a reason for hiding this comment

antgamdia commented May 13, 2022 •

edited

Loading

netlify bot commented May 13, 2022 •

edited

Loading

antgamdia commented May 13, 2022 •

edited

Loading