implement documentation syncing with containerd/containerd and on-site rendering by haddscot · Pull Request #214 · containerd/containerd.io

haddscot · 2024-03-11T21:00:28Z

addresses #163
built on top of #121

this PR implements:

tools/refresh-docs.sh -- script to be called by Makefile [make refresh-docs – also made it a dependency of make serve and make *-build]
.github/workflows/sync-documentation.yml -- github workflow to call make refresh-docs on a cron schedule of daily at 3am, same as sync-releases.yml. ~~currently set to operate as a pull request, and will currently generate doc sync PR on any other PR creation for the sake of demonstration, but will remove the on: pull_request: ... before merging~~
themes/containerd/layouts/partials/sidebar.html and nested-menu-partial.html -- adapted from hugocodex Auto-collapsing menu, enables browsing documentation

Signed-off-by: Kazuyoshi Kato <katokazu@amazon.com>

.github/workflows/sync-documentation.yml

content/docs/v1.2.x/_index.md

estesp · 2024-03-14T14:56:13Z

Looking at the preview here: https://deploy-preview-214--containerd-io.netlify.app/

This is promising progress, but I wonder how we can clean up the footer as shown in the below screen capture? Looks like these are directory names and are listed once for each file in the dir?

haddscot · 2024-03-14T17:20:09Z

Looking at the preview here: https://deploy-preview-214--containerd-io.netlify.app/

This is promising progress, but I wonder how we can clean up the footer as shown in the below screen capture? Looks like these are directory names and are listed once for each file in the dir?

I didn't even notice that, tunnel visioning on the body content.

will replace with links to docs home and the readme and getting started pages for 1.7.x and 1.6.x

haddscot · 2024-03-15T00:16:47Z

shortfalls that should be addressed in followup tasks:

images that are linked relative to the file structure of the markdown must be linked relative to the root of the containerd/containerd project, so that when they are rendered to html they will be linked relative to the corresponding v... directory [e.g. v1.7.x]. for example:

the architecture diagram on the 1.7.x README renders because it is linked as ![architecture](docs/historical/design/architecture.png) in the markdown, which is a path relative to the root of the project
the architecture diagram does not render at /docs/v1.7.x/docs/historical/design/architecture/ because it is linked as ![Architecture](architecture.png) in the markdown, which is a link relative to the /docs/historical/design/ directory and not the root of the project.

images that are in the repo but not in the docs/ directory aren't currently synced:

see the architecture diagram on the 1.6.x README which was in the design/ directory for that release.

in today's community call, we discussed the possibility of the auto-generated title pages that are used to give the sidebar navigation menu its hierarchical structure and dropdown names could potentially be fully fleshed out sub-READMEs.
using the weight md header, we could order the docs in the sidebar in a more logical way, so that the Getting Started page isn't listed 4th under docs/ because of the default alphabetization

haddscot · 2024-03-15T00:18:39Z

pinging @kzys @chalin since you both worked on the previous iterations of this task

chalin

Great to see progress on #163!

A few drive-by comments:

As mentioned in #163, I strongly suggest option (1), because it is simplest. Failing that, option (2): use git submodules.

What is proposed here feels like a custom (and deferred) kind of git "submodules", that will make it challenging to have reproducible builds.
Can you find a way to avoid having "docs" in doc page paths? E.g. /docs/v1.6.x/getting-started/ rather than /docs/v1.6.x/docs/getting-started/.
Switching to use Docsy might make your lives easier when it comes to managing doc versions.

/cc @natedoubleu @caniszczyk

chalin · 2024-03-15T19:22:03Z

netlify.toml


 [build.environment]
-HUGO_VERSION = "0.111.3"
+HUGO_VERSION = "0.123.7"


Unless you really need Hugo 0.123.7, I'd suggest that you upgrade the Hugo version separately to have having too many moving parts. Hugo 0.123.x has a rewritten core, and they're still ironing out the bugs, e.g., see open-telemetry/opentelemetry.io#4064.

I just needed to upgrade to 0.116.0+ to access the "like" operator on the "where" function

is there a version you would recommend?

gonna use ~~0.122.0~~ 0.116.0 for now since it's the last release before the rewritten core, and because newer versions run into weird errors building jquery

chalin · 2024-03-15T19:23:50Z

themes/containerd/layouts/index.html


      <div class="buttons is-centered">
-        <a class="button is-medium is-radiusless is-borderless has-text-weight-bold" href="/docs/getting-started">
+        <a class="button is-medium is-radiusless is-borderless has-text-weight-bold" href="/docs/v1.7.x/docs/getting-started/">


You might want to use /docs/latest and define a redirect rule that refers back to the latest version.

haddscot · 2024-03-18T22:39:42Z

A few drive-by comments:

As mentioned in Host documentation on the website, rather than linking to GH repo #163, I strongly suggest option (1), because it is simplest. Failing that, option (2): use git submodules.
What is proposed here feels like a custom (and deferred) kind of git "submodules", that will make it challenging to have reproducible builds.

✅ rewrote refresh-docs.sh to use submodules instead

Can you find a way to avoid having "docs" in doc page paths? E.g. /docs/v1.6.x/getting-started/ rather than /docs/v1.6.x/docs/getting-started/.

I could, but the reason I did it this way is because of the relative links to images and other pages in the original markdown – see the first example here. maintaining the directory structure – i.e. treating https://containerd.io/docs/v{$X_VERSION}.x/ as equivalent to the containerd project root – prevents us from having to do changes the links in the markdown

Switching to use Docsy might make your lives easier when it comes to managing doc versions.

can you clarify what specifically you mean when you say "managing doc versions"? the way I see it, this change doesn't add any responsibility of managing doc versions to the .io repo beyond simply updating to whatever the latest changes are on the specified branches of the containerd repo on a daily cadence.

haddscot · 2024-03-19T18:53:47Z

squashed everything up to this point because of trailing whitespace errors in the CI job

Signed-off-by: Scott Haddlesey <haddscot@amazon.com>

AkihiroSuda · 2025-03-27T23:50:19Z

themes/containerd/layouts/partials/footer.html

+            </a>
+          </li>
+          <li>
+            <a href="/docs/v1.7.x/">


v2.0.x needs to be added now

Probably there should be main too

akhilerm

Got 2 questions and comments.

akhilerm · 2025-04-01T16:50:57Z

.github/workflows/sync-documentation.yml

+  update-documentationmd:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3


Suggested change

- uses: actions/checkout@v3

- uses: actions/checkout@v4

akhilerm · 2025-04-01T16:51:43Z

.gitmodules

q: Should we add 2.0 also into the submodules?

akhilerm · 2025-04-01T16:52:54Z

content/docs/_index.md


-See https://github.com/containerd .
+- [1.7.x](v1.7.x/docs/getting-started/)
+- [1.6.x](v1.6.x/docs/getting-started/)


Can you add 2.0.x also here?

AkihiroSuda · 2025-04-08T07:13:07Z

@haddscot Do you plan to update this PR, or shall we carry this?

AkihiroSuda · 2025-04-14T01:35:25Z

yarn.lock

 bulma@^0.9.4:
  version "0.9.4"
-  resolved "https://registry.yarnpkg.com/bulma/-/bulma-0.9.4.tgz#0ca8aeb1847a34264768dba26a064c8be72674a1"
+  resolved "https://registry.npmjs.org/bulma/-/bulma-0.9.4.tgz"


samuelkarp · 2026-01-09T19:19:46Z

close/reopen to trigger netlify (preview build expired)

Add documents from containerd/containerd

7a09fba

Signed-off-by: Kazuyoshi Kato <katokazu@amazon.com>

AkihiroSuda reviewed Mar 12, 2024

View reviewed changes

.github/workflows/sync-documentation.yml Outdated Show resolved Hide resolved

AkihiroSuda reviewed Mar 12, 2024

View reviewed changes

content/docs/v1.2.x/_index.md Outdated Show resolved Hide resolved

haddscot force-pushed the squash_doc_hosting branch from 1c93a74 to fd837a5 Compare March 12, 2024 23:18

chalin reviewed Mar 15, 2024

View reviewed changes

haddscot force-pushed the squash_doc_hosting branch 3 times, most recently from 4dba8bd to 30d9000 Compare March 18, 2024 22:19

haddscot force-pushed the squash_doc_hosting branch 3 times, most recently from a19ec84 to 20cb44d Compare March 19, 2024 18:52

implement doc hosting and syncing

8c9946d

Signed-off-by: Scott Haddlesey <haddscot@amazon.com>

haddscot force-pushed the squash_doc_hosting branch from 20cb44d to 8c9946d Compare March 19, 2024 20:09

haddscot requested a review from chalin March 27, 2024 17:01

AkihiroSuda requested review from estesp and removed request for chalin September 18, 2024 23:41

AkihiroSuda requested a review from samuelkarp March 27, 2025 23:49

AkihiroSuda reviewed Mar 27, 2025

View reviewed changes

akhilerm reviewed Apr 1, 2025

View reviewed changes

AkihiroSuda requested a review from kzys April 8, 2025 07:13

AkihiroSuda reviewed Apr 14, 2025

View reviewed changes

samuelkarp closed this Jan 9, 2026

samuelkarp reopened this Jan 9, 2026

Conversation

haddscot commented Mar 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

estesp commented Mar 14, 2024

Uh oh!

haddscot commented Mar 14, 2024

Uh oh!

haddscot commented Mar 15, 2024

Uh oh!

haddscot commented Mar 15, 2024

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haddscot Mar 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haddscot commented Mar 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

haddscot commented Mar 19, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akhilerm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda commented Apr 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samuelkarp commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

haddscot commented Mar 11, 2024 •

edited

Loading

haddscot Mar 18, 2024 •

edited

Loading

haddscot commented Mar 18, 2024 •

edited

Loading