diff --git a/.gitignore b/.gitignore index 01a54c0679..51e94f41b4 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,4 @@ resources/ # Netlify Functions build output package-lock.json functions/ -node_modules/ +node_modules/ \ No newline at end of file diff --git a/.htmltest.yml b/.htmltest.yml new file mode 100644 index 0000000000..7f73da988e --- /dev/null +++ b/.htmltest.yml @@ -0,0 +1,16 @@ +DirectoryPath: public/docs +IgnoreDirectoryMissingTrailingSlash: true +CheckExternal: false +IgnoreAltMissing: true +CheckImages: false +CheckScripts: false +CheckMeta: false +CheckMetaRefresh: false +CheckLinks: false +EnforceHTML5: false +EnforceHTTPS: false +IgnoreDirectoryMissingTrailingSlash: false +IgnoreInternalEmptyHash: true +IgnoreEmptyHref: true +IgnoreDirs: + - "reference/generated/kubernetes-api" \ No newline at end of file diff --git a/Makefile b/Makefile index 75d37f767d..10ed40aac7 100644 --- a/Makefile +++ b/Makefile @@ -50,3 +50,11 @@ docker-serve: test-examples: scripts/test_examples.sh install scripts/test_examples.sh run + +.PHONY: link-checker-setup +link-checker-image-pull: + docker pull wjdp/htmltest + +docker-internal-linkcheck: link-checker-image-pull + $(DOCKER_RUN) $(DOCKER_IMAGE) hugo --config config.toml,linkcheck-config.toml --buildFuture + $(DOCKER) run --mount type=bind,source=$(CURDIR),target=/test --rm wjdp/htmltest htmltest \ No newline at end of file diff --git a/config.toml b/config.toml index 05430dc87b..4acaa66e95 100644 --- a/config.toml +++ b/config.toml @@ -313,4 +313,4 @@ contentDir = "content/uk" [languages.uk.params] time_format_blog = "02.01.2006" # A list of language codes to look for untranslated content, ordered from left to right. -language_alternatives = ["en"] +language_alternatives = ["en"] \ No newline at end of file diff --git a/content/en/docs/concepts/architecture/cloud-controller.md b/content/en/docs/concepts/architecture/cloud-controller.md index 1891a2d10b..31c0ad9d54 100644 --- a/content/en/docs/concepts/architecture/cloud-controller.md +++ b/content/en/docs/concepts/architecture/cloud-controller.md @@ -212,4 +212,4 @@ The cloud controller manager uses Go interfaces to allow implementations from an The implementation of the shared controllers highlighted in this document (Node, Route, and Service), and some scaffolding along with the shared cloudprovider interface, is part of the Kubernetes core. Implementations specific to cloud providers are outside the core of Kubernetes and implement the `CloudProvider` interface. For more information about developing plugins, see [Developing Cloud Controller Manager](/docs/tasks/administer-cluster/developing-cloud-controller-manager/). -{{% /capture %}} +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/contribute/new-content/overview.md b/content/en/docs/contribute/new-content/overview.md index 831ed12a7a..11f4c067d7 100644 --- a/content/en/docs/contribute/new-content/overview.md +++ b/content/en/docs/contribute/new-content/overview.md @@ -54,5 +54,8 @@ was wrong, you (and only you, the submitter) can change it. Limit pull requests to one language per PR. If you need to make an identical change to the same code sample in multiple languages, open a separate PR for each language. +## Tools for contributors + +The [doc contributors tools](https://github.com/kubernetes/website/tree/master/content/en/docs/doc-contributor-tools) directory in the `kubernetes/website` repository contains tools to help your contribution journey go more smoothly. {{% /capture %}} diff --git a/content/en/docs/doc-contributor-tools/linkchecker/README.md b/content/en/docs/doc-contributor-tools/linkchecker/README.md new file mode 100644 index 0000000000..a575c4d1fe --- /dev/null +++ b/content/en/docs/doc-contributor-tools/linkchecker/README.md @@ -0,0 +1,76 @@ +# Internal link checking tool + +You can use [htmltest](https://github.com/wjdp/htmltest) to check for broken links in [`/content/en/`](https://git.k8s.io/website/content/en/). This is useful when refactoring sections of content, moving pages around, or renaming files or page headers. + +## How the tool works + +`htmltest` scans links in the generated HTML files of the kubernetes website repository. It runs using a `make` command which does the following: + +- Builds the site and generates output HTML in the `/public` directory of your local `kubernetes/website` repository +- Pulls the `wdjp/htmltest` Docker image +- Mounts your local `kubernetes/website` repository to the Docker image +- Scans the files generated in the `/public` directory and provides command line output when it encounters broken internal links + +## What it does and doesn't check + +The link checker scans generated HTML files, not raw Markdown. The htmltest tool depends on a configuration file, [`.htmltest.yml`](https://git.k8s.io/website/.htmltest.yml), to determine which content to examine. + +The link checker scans the following: + +- All content generated from Markdown in [`/content/en/docs`](https://git.k8s.io/website/content/en/docs/) directory, excluding: + - Generated API references, for example https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- All internal links, excluding: + - Empty hashes (`` or `[title](#)`) and empty hrefs (`` or `[title]()`) + - Internal links to images and other media files + +The link checker does not scan the following: + +- Links included in the top and side nav bars, footer links, or links in a page's `` section, such as links to CSS stylesheets, scripts, and meta information +- Top level pages and their children, for example: `/training`, `/community`, `/case-studies/adidas` +- Blog posts +- API Reference documentation, for example: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- Localizations + +## Prerequisites and installation + +You must install +* [Docker](https://docs.docker.com/get-docker/) +* [make](https://www.gnu.org/software/make/) + +## Running the link checker + +To run the link checker: + +1. Navigate to the root directory of your local `kubernetes/website` repository. + +2. Run the following command: + + ``` + make docker-internal-linkcheck + ``` + +## Understanding the output + +If the link checker finds broken links, the output is similar to the following: + +``` +tasks/access-kubernetes-api/custom-resources/index.html + hash does not exist --- tasks/access-kubernetes-api/custom-resources/index.html --> #preserving-unknown-fields + hash does not exist --- tasks/access-kubernetes-api/custom-resources/index.html --> #preserving-unknown-fields +``` + +This is one set of broken links. The log adds an output for each page with broken links. + +In this output, the file with broken links is `tasks/access-kubernetes-api/custom-resources.md`. + +The tool gives a reason: `hash does not exist`. In most cases, you can ignore this. + +The target URL is `#preserving-unknown-fields`. + +One way to fix this is to: + +1. Navigate to the Markdown file with a broken link. +2. Using a text editor, do a full-text search (usually Ctrl+F or Command+F) for the broken link's URL, `#preserving-unknown-fields`. +3. Fix the link. For a broken page hash (or _anchor_) link, check whether the topic was renamed or removed. + +Run htmltest to verify that broken links are fixed. \ No newline at end of file diff --git a/content/en/docs/home/_index.md b/content/en/docs/home/_index.md index dcaf693039..6b6e77c39a 100644 --- a/content/en/docs/home/_index.md +++ b/content/en/docs/home/_index.md @@ -15,7 +15,7 @@ menu: title: "Documentation" weight: 20 post: > -

Learn how to use Kubernetes with conceptual, tutorial, and reference documentation. You can even help contribute to the docs!

+

Learn how to use Kubernetes with conceptual, tutorial, and reference documentation. You can even help contribute to the docs!

description: > Kubernetes is an open source container orchestration engine for automating deployment, scaling, and management of containerized applications. The open source project is hosted by the Cloud Native Computing Foundation. overview: > @@ -38,7 +38,7 @@ cards: button_path: "/docs/setup" - name: tasks title: "Learn how to use Kubernetes" - description: "Look up common tasks and how to perform them using a short sequence of steps." + description: "Look up common tasks and how to perform them using a short sequence of steps." button: "View Tasks" button_path: "/docs/tasks" - name: training @@ -62,4 +62,4 @@ cards: - name: about title: About the documentation description: This website contains documentation for the current and previous 4 versions of Kubernetes. ---- +--- \ No newline at end of file diff --git a/layouts/partials/docs/content-page.html b/layouts/partials/docs/content-page.html index 85bac1d994..c6ece3e527 100644 --- a/layouts/partials/docs/content-page.html +++ b/layouts/partials/docs/content-page.html @@ -1,7 +1,7 @@ {{- $filepath := .page.File.Path }} {{- $editLink := printf "https://github.com/kubernetes/website/edit/master/content/%s/%s" .page.Language.Lang $filepath }}

- + Edit This Page

@@ -15,4 +15,4 @@ {{ .page.TableOfContents }} {{ end }} {{ .page.Content }} -{{ end }} +{{ end }} \ No newline at end of file diff --git a/layouts/partials/docs/top-menu.html b/layouts/partials/docs/top-menu.html index a8425a014c..c1654dbcd1 100644 --- a/layouts/partials/docs/top-menu.html +++ b/layouts/partials/docs/top-menu.html @@ -12,10 +12,10 @@ - + \ No newline at end of file diff --git a/layouts/partials/footer.html b/layouts/partials/footer.html index e132e3df38..17f64c793c 100644 --- a/layouts/partials/footer.html +++ b/layouts/partials/footer.html @@ -1,10 +1,10 @@ + \ No newline at end of file diff --git a/layouts/partials/header.html b/layouts/partials/header.html index 44365f8ecb..28fbc9e98f 100644 --- a/layouts/partials/header.html +++ b/layouts/partials/header.html @@ -1,40 +1,40 @@
- +
+ \ No newline at end of file diff --git a/layouts/partials/tree.html b/layouts/partials/tree.html index 568f5e4027..ca742a1293 100644 --- a/layouts/partials/tree.html +++ b/layouts/partials/tree.html @@ -1,9 +1,9 @@ - + {{ template "section-tree-nav" (dict "ctx" . "section" .) }} {{ define "section-tree-nav" }} {{ $pages := (union .section.Pages .section.Sections) }} {{ with site.Params.language_alternatives }} - {{ range . }} + {{ range . }} {{ with (where $.section.Translations ".Lang" . ) }} {{ $p := index . 0 }} {{ $pages = $pages | lang.Merge (union $p.Pages $p.Sections) }} @@ -25,7 +25,7 @@ {{ if ge (len .section.Content) 10 }} {{/* The section page has content, so link to it. */}} {{ $isForeignLanguage := (ne .section.Lang $.ctx.Lang)}} - + {{ end }} {{ template "section-tree-nav" . }} @@ -33,5 +33,5 @@ {{ end }} {{ define "section-tree-nav-page" }} {{ $isForeignLanguage := (ne .page.Lang $.ctx.Lang)}} - -{{ end }} + +{{ end }} \ No newline at end of file diff --git a/linkcheck-config.toml b/linkcheck-config.toml new file mode 100644 index 0000000000..60015a74f1 --- /dev/null +++ b/linkcheck-config.toml @@ -0,0 +1 @@ +canonifyURLs = true \ No newline at end of file