implement doc hosting and syncing

haddscot · haddscot · commit 8c9946d187d4 · 2024-03-19T13:09:01.000-07:00
Signed-off-by: Scott Haddlesey &lt;haddscot@amazon.com&gt;
diff --git a/.github/workflows/sync-documentation.yml b/.github/workflows/sync-documentation.yml
@@ -0,0 +1,14 @@
+name: Sync-Documentation
+
+on:
+  schedule:
+    - cron:  '0 3 * * *'
+
+jobs:
+  update-documentationmd:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Update documentation
+        id: vars
+        run: make refresh-docs
diff --git a/.gitignore b/.gitignore
@@ -7,7 +7,12 @@ node_modules/
 # Hugo-generated assets
 public/
 resources/
+.hugo_build.lock
 
 # Link checker assets
 bin/
 tmp/
+
+# Documentation synced from other repos
+content/docs/v*
+static/docs/*
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,8 @@
+[submodule "containerd1.7"]
+	path = containerd1.7
+	url = https://github.com/containerd/containerd.git
+	branch = release/1.7
+[submodule "containerd1.6"]
+	path = containerd1.6
+	url = https://github.com/containerd/containerd.git
+	branch = release/1.6
diff --git a/Makefile b/Makefile
@@ -15,29 +15,20 @@
 clean:
 	rm -rf public resources
 
-containerd-1.7.x:
-	git clone --branch v1.7.0 --depth 1 https://github.com/containerd/containerd.git containerd-1.7.x
+refresh-docs:
+	./tools/refresh-docs.sh
 
-content/v1.7.x: containerd-1.7.x
-	cp -r containerd-1.7.x/docs content/v1.7.x
-
-containerd-1.6.x:
-	git clone --branch v1.6.19 --depth 1 https://github.com/containerd/containerd.git containerd-1.6.x
-
-content/v1.6.x: containerd-1.6.x
-	cp -r containerd-1.6.x/docs content/v1.6.x
-
-serve: content/v1.7.x content/v1.6.x
+serve: refresh-docs
 	hugo server \
 		--buildDrafts \
 		--buildFuture \
 		--disableFastRender
 
-production-build: content/v1.7.x content/v1.6.x
+production-build: refresh-docs
 	hugo \
 	--minify
 
-preview-build: content/v1.7.x content/v1.6.x
+preview-build: refresh-docs
 	hugo \
 		--baseURL $(DEPLOY_PRIME_URL) \
 		--buildDrafts \
diff --git a/README.md b/README.md
@@ -38,15 +38,13 @@ You can also access the deploy preview for a pull request by clicking **Show all
 
 ## Contributing to the documentation
 
-All of containerd's documentation is written in [GitHub-flavored Markdown](https://github.github.com/gfm/) and contained in the [`content/docs`](content/docs) folder.
+The source of truth for containerd's documentation is the [`docs folder`](https://github.com/containerd/containerd/tree/main/docs) in the containerd/containerd repo. Documentation is syncronized to this repo daily using the [Sync-Documentation](/.github/workflows/sync-documentation.yml) workflow.
 
 ### Adding new docs
 
-To create a new doc, add a Markdown file to `content/docs`. The name of the file will determine its URL. This doc, for example, would be available at `https://containerd.io/docs/client-libraries`:
+All of containerd's documentation is written in [GitHub-flavored Markdown](https://github.github.com/gfm/). To create a new doc, add a Markdown file in the [`docs folder`](https://github.com/containerd/containerd/tree/main/docs) in the containerd/containerd repo, and it will automatically be cloned into this repo. **DO NOT WRITE DOCUMENTATION DIRECTLY TO THIS REPO -- IT WILL BE DELETED BY THE SYNC-DOCUMENTATION WORKFLOW.**
 
-```shell
-touch content/docs/client-libraries.md
-```
+The name, path, and release branch of the file in the containerd/containerd repo will determine its URL on this site. For example, a document committed to `https://github.com/containerd/containerd/blob/release/1.7/docs/NRI.md` would be available at `https://containerd.io/docs/v1.7.x/nri/`.
 
 Once you've added the doc you'll need to add the following page metadata at the top, as YAML:
 
diff --git a/containerd1.6 b/containerd1.6
@@ -0,0 +1 @@
+Subproject commit d68034c2fe20ce0fc29692f87afced1edf7d77da
diff --git a/containerd1.7 b/containerd1.7
@@ -0,0 +1 @@
+Subproject commit dcf2847247e18caba8dce86522029642f60fe96b
diff --git a/content/docs/_index.md b/content/docs/_index.md
@@ -4,14 +4,17 @@ short: Overview
 weight: 1
 ---
 
-Welcome to the containerd documentation! This document contains some basic project-level information about containerd.
+## Overview
 
-If you'd like to get started running containerd locally on your machine, see the [Getting started](https://github.com/containerd/containerd/blob/main/docs/getting-started.md) guide.
+Welcome to the containerd documentation! This document contains some basic project-level information about containerd.
 
-See also other docs: https://github.com/containerd/containerd/tree/main/docs
+If you'd like to get started running containerd locally on your machine, see the [getting started](#getting-started) guide.
 
 ## Repositories
 
-The containerd project is encapsulated in a variety of [GitHub](https://github.com) repositories.
+The containerd project is encapsulated in a variety of GitHub repositories; see https://github.com/containerd .
+
+## Getting Started
 
-See https://github.com/containerd .
+- [1.7.x](v1.7.x/docs/getting-started/)
+- [1.6.x](v1.6.x/docs/getting-started/)
diff --git a/content/docs/getting-started.md b/content/docs/getting-started.md
@@ -4,5 +4,4 @@ short: Getting started
 weight: 2
 ---
 
-- [1.7.x](/v1.7.x/getting-started/)
-- [1.6.x](/v1.6.x/getting-started/)
+This page has been consolidated to the [overview page](/docs/#getting-started)
diff --git a/netlify.toml b/netlify.toml
@@ -3,7 +3,7 @@ publish = "public"
 command = "make production-build"
 
 [build.environment]
-HUGO_VERSION = "0.111.3"
+HUGO_VERSION = "0.116.0"
 
 [context.deploy-preview]
 command = "make preview-build"
diff --git a/package-lock.json b/package-lock.json
diff --git a/themes/containerd/layouts/docs/list.html b/themes/containerd/layouts/docs/list.html
@@ -1,34 +1,38 @@
 {{ define "title" }}
-containerd docs &ndash; {{ .Title }}
+containerd docs &ndash; {{ cond (eq .Title "") (.File.BaseFileName | humanize | title) .Title }}
 {{ end }}
 
 {{ define "main" }}
 {{- $section := .Section }}
 {{- $pages   := where .Site.Pages "Section" $section }}
 
 {{ partial "hero.html" . }}
-{{ partial "docs/tabs.html" (dict "pages" $pages "currentUrl" .RelPermalink) }}
+{{ $Content := .Content }}
 
 <article class="is-{{ $section }}-article">
   <div class="container">
     <div class="columns">
-      <div class="column is-three-quarters is-full-mobile">
+      {{ partial "docs/sidebar.html" . }}
+
+      <div class="column is-two-thirds is-full-mobile">
         <div class="content">
           <div class="is-hidden-desktop">
             {{ partial "docs/dropdown.html" . }}
           </div>
     
           <section class="is-inner-content">
-            {{ .Content }}
+            <!-- remove instances of .md to fix links to other docs -->
+            {{- $content := (replaceRE `\.md` "" .Content) }}
+            {{ $content | safeHTML }}
           </section>
         </div>
       </div>
 
       <div class="column is-hidden-touch">
         {{- if .TableOfContents }}
         <aside class="is-toc-container">
-          <p class="is-size-4 is-toc-title">
-            Table of contents
+          <p class="is-toc-title">
+            On this page
           </p>
 
           <div id="toc">
diff --git a/themes/containerd/layouts/docs/single.html b/themes/containerd/layouts/docs/single.html
@@ -1,25 +1,29 @@
 {{ define "title" }}
-containerd docs &ndash; {{ .Title }}
+{{- $title := .Title }}
+containerd docs &ndash; {{ cond (eq .Title "") (.File.BaseFileName | humanize | title) .Title }}
 {{ end }}
 
 {{ define "main" }}
 {{- $section := .Section }}
 {{- $pages := where .Site.Pages "Section" "docs" }}
 
 {{ partial "hero.html" . }}
-{{ partial "docs/tabs.html" (dict "pages" $pages "currentUrl" .RelPermalink) }}
 
 <article class="is-{{ $section }}-article">
-  <div class="container">
+  <div class="container margin-top: 50px">
     <div class="columns">
-      <div class="column is-three-quarters is-full-mobile">
+      {{ partial "docs/sidebar.html" . }}
+
+      <div class="column is-two-thirds is-full-mobile">
         <div class="content">
           <div class="is-hidden-desktop">
             {{ partial "docs/dropdown.html" . }}
           </div>
-    
+
           <section class="is-inner-content">
-            {{ .Content }}
+            <!-- remove instances of .md to fix links to other docs -->
+            {{- $content := (replaceRE `\.md` "" .Content) }}
+            {{ $content | safeHTML }}
           </section>
         </div>
       </div>
@@ -28,7 +32,7 @@
         {{- if .TableOfContents }}
         <aside class="is-toc-container">
           <p class="is-size-4 is-toc-title">
-            Table of contents
+            On this page
           </p>
 
           <div id="toc">
diff --git a/themes/containerd/layouts/index.html b/themes/containerd/layouts/index.html
@@ -20,7 +20,7 @@
       <br />
 
       <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/">
           <span class="icon">
             <i class="fas fa-sm fa-step-forward"></i>
           </span>
diff --git a/themes/containerd/layouts/partials/docs/dropdown.html b/themes/containerd/layouts/partials/docs/dropdown.html
@@ -1,5 +1,7 @@
 {{- $currentUrl := .RelPermalink }}
-{{- $docs       := where .Site.Pages "Section" "docs" }}
+{{- $xVersion := index (findRE `v\d+\.\d+\.x` .RelPermalink) 0 }}
+{{- $docs := where site.RegularPages "CurrentSection.Path" "like" (printf "%s%s%s" "/docs/" $xVersion ".*") }}
+
 <div class="dropdown">
   <div class="dropdown-trigger">
     <button class="button is-dark" aria-haspopup="true" aria-controls="docs-dropdown-menu">
@@ -11,10 +13,21 @@
   </div>
   <div class="dropdown-menu" id="docs-dropdown-menu" role="menu">
     <div class="dropdown-content">
+      <a class="dropdown-item{{ if eq .RelPermalink `/docs/` }} is-active{{ end }}" href="/docs">
+        Docs Home
+      </a>
+
+      {{ if (strings.Contains $xVersion "v") }}
+      {{- $readmeURL := (printf "%s%s%s" "/docs/" $xVersion "/") }}
+      <a href="{{$readmeURL}}" class="dropdown-item{{ if eq .RelPermalink $readmeURL }} is-active{{ end }}">
+          README
+      </a>
+      {{ end }}
+
       {{- range $docs }}
       {{- $isCurrentPage := eq $currentUrl .RelPermalink }}
       <a class="dropdown-item{{ if $isCurrentPage }} is-active{{ end }}" href="{{ .RelPermalink }}">
-        {{ .Title }}
+        {{ cond (eq .Title "") (.File.BaseFileName | humanize | title) .Title }}
       </a>
       {{- end }}
     </div>
diff --git a/themes/containerd/layouts/partials/docs/nested-menu-partial.html b/themes/containerd/layouts/partials/docs/nested-menu-partial.html
@@ -0,0 +1,14 @@
+{{ range .context.Pages }}
+    <li class="{{ if or (in $.ancestors .) (eq $.curRelPermalink .RelPermalink) }}active{{ end }} {{ if len .Pages }}haschildren{{ end }}">
+        {{ if not (len .Pages) }}
+            <a href="{{ .RelPermalink }}">{{ cond (eq .Title "") (.File.BaseFileName | humanize | title) .Title }}</a>
+        {{ else }}
+            <a onclick="this.parentNode.classList.contains('active') ? this.parentNode.classList.remove('active') : this.parentElement.classList.add('active')">
+                {{ cond (eq .Title "") (.File.BaseFileName | humanize | title) .Title }}
+            </a>
+        {{ end }}
+        <ul>
+            {{ partial "docs/nested-menu-partial.html" (dict "curRelPermalink" $.curRelPermalink "ancestors" $.ancestors "context" .) }}
+        </ul>
+    </li>
+{{ end }}
diff --git a/themes/containerd/layouts/partials/docs/sidebar.html b/themes/containerd/layouts/partials/docs/sidebar.html
@@ -0,0 +1,43 @@
+{{- $currentUrl := .RelPermalink }}
+{{- $xVersion := index (findRE `v\d+\.\d+\.x` .RelPermalink) 0 }}
+
+{{- $docs := where site.RegularPages "CurrentSection.Path" (printf "%s%s" "/docs/" $xVersion) }}
+
+<style>
+    ul.nestedmenu {margin-left: 0;}
+    ul.nestedmenu li {list-style: none;}
+    ul.nestedmenu li > ul {display: none;}
+    ul.nestedmenu li > a::before {content: "•"; display: inline-block; margin-right: 0.25rem; width: 0.5rem; text-align: center;}
+    ul.nestedmenu li.haschildren > a::before {content: "›";}
+    ul.nestedmenu li.haschildren.active > a::before {transform: rotate(90deg);}
+    ul.nestedmenu li.active > ul {display: block;}
+    ul.nestedmenu li > a {color: #444444!important;}
+    ul.nestedmenu li.active > a {color: rgb(247, 44, 114)!important;}
+</style>
+
+<aside class="column is-hidden-touch is-fullheight is-hidden-mobile">
+<ul class="menu-list">
+    <li>
+    <a href="/docs" class="{{ if eq .RelPermalink `/docs/` }} is-active{{ end }}">
+        <span class="icon"><i class="fa fa-home"></i></span> Docs Home
+    </a>
+    </li>
+
+    {{ if (strings.Contains $xVersion "v") }}
+    {{- $readmeURL := (printf "%s%s%s" "/docs/" $xVersion "/") }}
+    <li>
+        <a href="{{$readmeURL}}" class="{{ if eq .RelPermalink $readmeURL }} is-active{{ end }}">
+            <span class="icon"><i class="fa fa-info"></i></span> README
+        </a>
+    </li>
+    {{ end }}
+
+    {{ .Scratch.Set "ancestors" .Ancestors }}
+    {{ .Scratch.Set "curRelPermalink" .RelPermalink }}
+    {{ with .Site.GetPage (print "/docs/" $xVersion "/_index.md") }}
+    <ul class="nestedmenu">
+        {{ partial "docs/nested-menu-partial.html" (dict "curRelPermalink" ($.Scratch.Get "curRelPermalink") "ancestors" ($.Scratch.Get "ancestors") "context" .) }}
+    </ul>
+    {{ end }}
+</ul>
+</aside>
diff --git a/themes/containerd/layouts/partials/docs/tabs.html b/themes/containerd/layouts/partials/docs/tabs.html
diff --git a/themes/containerd/layouts/partials/footer.html b/themes/containerd/layouts/partials/footer.html
diff --git a/themes/containerd/layouts/partials/hero.html b/themes/containerd/layouts/partials/hero.html
diff --git a/themes/containerd/layouts/partials/navbar.html b/themes/containerd/layouts/partials/navbar.html
diff --git a/tools/refresh-docs.sh b/tools/refresh-docs.sh
diff --git a/yarn.lock b/yarn.lock
