Merge pull request #219 from smlx/docs-bitrot

docs bitrot

.github/workflows/user-documentation.yaml

@@ -1,6 +1,7 @@
 name: User Documentation
 
 on:
+  pull_request:
   push:
     branches:
     - main  # Set a branch to deploy
@@ -15,27 +16,18 @@ jobs:
       with:
         fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
 
-    - uses: actions/checkout@v4
-      with:
-        repository: google/docsy
-        path: docs/themes/docsy
-        submodules: true
-
     - name: Setup Hugo
       uses: peaceiris/actions-hugo@v2
       with:
+        hugo-version: '0.123.8'
         extended: true
 
     - name: Setup Node
       uses: actions/setup-node@v4
       with:
-        node-version: '16'
-
-    - run: cd docs && npm install postcss postcss-cli autoprefixer
-
-    - run: cd docs/themes/docsy && npm install
+        node-version: 20
 
-    - run: cd docs && hugo --minify
+    - run: cd docs && npm install postcss-cli autoprefixer && hugo --minify
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3

docs/.gitignore

@@ -2,5 +2,6 @@
 /node_modules
 /package-lock.json
 /package.json
+/public
 /resources
 /themes

docs/Makefile

@@ -1,9 +1,13 @@
 .PHONY: serve
-serve: themes/docsy
+serve:
 	cd .. && \
-		docker run --rm -it -v $$(pwd):/src -u $$(id -u) -p 1313:1313 \
-		--entrypoint sh klakegg/hugo:ext-alpine -c \
-		'cd docs && npm install postcss postcss-cli autoprefixer && hugo --baseURL=/ --bind=0.0.0.0 serve'
+		docker run --rm -it -v $$(pwd):/src -v $$HOME/.cache/hugo_cache:/home/node/.cache/hugo_cache -u $$(id -u) -p 1313:1313 \
+		--entrypoint sh hugomods/hugo:latest -c \
+		"cd docs && hugo server --baseURL=/ --bind 0.0.0.0"
 
-themes/docsy:
-	git clone --recurse-submodules http://github.com/google/docsy themes/docsy
+.PHONY: minify
+minify:
+	cd .. && \
+		docker run --rm -it -v $$(pwd):/src -v $$HOME/.cache/hugo_cache:/home/node/.cache/hugo_cache -u $$(id -u)\
+		--entrypoint sh hugomods/hugo:latest -c \
+		"cd docs && npm install postcss-cli autoprefixer && hugo --minify"

docs/assets/scss/_variables_project.scss

@@ -0,0 +1,6 @@
+/*
+
+Add styles or override variables from the theme here.
+
+*/
+

docs/go.mod

@@ -0,0 +1,5 @@
+module github.com/google/docsy-example
+
+go 1.12
+
+require github.com/google/docsy v0.9.1 // indirect

docs/go.sum

@@ -0,0 +1,5 @@
+github.com/FortAwesome/Font-Awesome v0.0.0-20240108205627-a1232e345536/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/google/docsy v0.9.1 h1:+jqges1YCd+yHeuZ1BUvD8V8mEGVtPxULg5j/vaJ984=
+github.com/google/docsy v0.9.1/go.mod h1:saOqKEUOn07Bc0orM/JdIF3VkOanHta9LU5Y53bwN2U=
+github.com/twbs/bootstrap v5.2.3+incompatible h1:lOmsJx587qfF7/gE7Vv4FxEofegyJlEACeVV+Mt7cgc=
+github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

docs/config.toml → docs/hugo.toml

@@ -1,22 +1,20 @@
 baseURL = "/piv-agent/"
 title = "PIV Agent"
 
-enableRobotsTXT = true
-
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
-theme = ["docsy"]
-
-# Will give values to .Lastmod etc.
-enableGitInfo = true
-
 # Language settings
 contentDir = "content/en"
 defaultContentLanguage = "en"
 defaultContentLanguageInSubdir = false
 # Useful when translating.
 enableMissingTranslationPlaceholders = true
 
-disableKinds = ["taxonomy", "taxonomyTerm"]
+enableRobotsTXT = true
+
+# Will give values to .Lastmod etc.
+enableGitInfo = true
+
+# Comment out to enable taxonomies in Docsy
+disableKinds = ["taxonomy"]
 
 # Highlighting config
 pygmentsCodeFences = true
@@ -31,58 +29,35 @@ pygmentsStyle = "tango"
 [permalinks]
 blog = "/:section/:year/:month/:day/:slug/"
 
-## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
-[blackfriday]
-plainIDAnchors = true
-hrefTargetBlank = true
-angledQuotes = false
-latexDashes = true
-
 # Image processing configuration.
 [imaging]
 resampleFilter = "CatmullRom"
 quality = 75
 anchor = "smart"
 
-[services]
-[services.googleAnalytics]
-# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
-# id = "UA-00000000-0"
-
 # Language configuration
 
 [languages]
 [languages.en]
-title = "PIV Agent"
-description = "PIV Agent replaces ssh-agent and gpg-agent, and allows you to use your PIV security token with SSH or GPG"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
-# [languages.no]
-# title = "Goldydocs"
-# description = "Docsy er operativsystem for skyen"
-# languageName ="Norsk"
-# contentDir = "content/no"
-# time_format_default = "02.01.2006"
-# time_format_blog = "02.01.2006"
-# 
-# [languages.fa]
-# title = "اسناد گلدی"
-# description = "یک نمونه برای پوسته داکسی"
-# languageName ="فارسی"
-# contentDir = "content/fa"
-# time_format_default = "2006.01.02"
-# time_format_blog = "2006.01.02"
+[languages.en.params]
+title = "PIV Agent"
+description = "PIV Agent replaces ssh-agent and gpg-agent, and allows you to use your PIV security token with SSH or GPG"
+
 
 [markup]
   [markup.goldmark]
+    [markup.goldmark.parser.attribute]
+      block = true
     [markup.goldmark.renderer]
       unsafe = true
   [markup.highlight]
-      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
-      style = "tango"
-      # Uncomment if you want your chosen highlight style used for code blocks without a specified language
-      # guessSyntax = "true"
+    # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
+    style = "tango"
+    # Uncomment if you want your chosen highlight style used for code blocks without a specified language
+    # guessSyntax = "true"
 
 # Everything below this are Site Params
 
@@ -91,23 +66,20 @@ weight = 1
 section = ["HTML", "print"]
 
 [params]
-copyright = "PIV Agent Contributors"
-# privacy_policy = "https://github.com/smlx/piv-agent"
-
 # First one is picked as the Twitter card image if not set on page.
 # images = ["images/project-illustration.png"]
 
 # Menu title if your navbar has a versions selector to access old versions of your site.
 # This menu appears only if you have at least one [params.versions] set.
 version_menu = "Releases"
 
-# Flag used in the "version-banner" partial to decide whether to display a 
+# Flag used in the "version-banner" partial to decide whether to display a
 # banner on every page indicating that this is an archived version of the docs.
 # Set this flag to "true" if you want to display the banner.
 archived_version = false
 
 # The version number for the version of the docs represented in this doc set.
-# Used in the "version-banner" partial to display a version number for the 
+# Used in the "version-banner" partial to display a version number for the
 # current doc set.
 version = "0.0"
 
@@ -118,87 +90,74 @@ url_latest_version = "https://example.com"
 # Repository configuration (URLs for in-page links to opening issues and suggesting changes)
 github_repo = "https://github.com/smlx/piv-agent"
 # An optional link to a related project repo. For example, the sibling repository where your product code lives.
-# github_project_repo = "https://github.com/smlx/piv-agent"
+# github_project_repo = "https://github.com/google/docsy"
 
 # Specify a value here if your content directory is not in your repo's root directory
-github_subdir = "docs"
+# github_subdir = ""
 
-# Uncomment this if you have a newer GitHub repo with "main" as the default branch,
+# Uncomment this if your GitHub repo does not have "main" as the default branch,
 # or specify a new value if you want to reference another branch in your GitHub links
 github_branch= "main"
 
 # Google Custom Search Engine ID. Remove or comment out to disable search.
-#gcs_engine_id = "d72aa9b2712488cc3"
-
-# Enable Algolia DocSearch
-algolia_docsearch = false
+# gcs_engine_id = "d72aa9b2712488cc3"
 
 # Enable Lunr.js offline search
 offlineSearch = true
 
 # Enable syntax highlighting and copy buttons on code blocks with Prism
 prism_syntax_highlighting = false
 
+[params.copyright]
+  authors = "PIV Agent Contributors | [CC BY SA 4.0](https://creativecommons.org/licenses/by-sa/4.0)"
+  from_year = 2020
+
 # User interface configuration
 [params.ui]
-# Enable to show the side bar menu in its compact state.
-sidebar_menu_compact = false
 #  Set to true to disable breadcrumb navigation.
 breadcrumb_disable = false
-#  Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
-sidebar_search_disable = false
-#  Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar
+# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
 navbar_logo = true
-# Set to true to disable the About link in the site footer
-footer_about_disable = false
+# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
+navbar_translucent_over_cover_disable = false
+# Enable to show the side bar menu in its compact state.
+sidebar_menu_compact = false
+# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
+sidebar_search_disable = false
 
 # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
 # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
 # If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
 # add "hide_feedback: true" to the page's front matter.
 [params.ui.feedback]
-enable = true
+enable = false
 # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
-yes = 'Glad to hear it! Please <a href="https://github.com/smlx/piv-agent/issues/new">tell us how we can improve</a>.'
-no = 'Sorry to hear that. Please <a href="https://github.com/smlx/piv-agent/issues/new">tell us how we can improve</a>.'
+yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
 
 # Adds a reading time to the top of each doc.
-# If you want this feature, but occasionally need to remove the Reading time from a single page, 
+# If you want this feature, but occasionally need to remove the Reading time from a single page,
 # add "hide_readingtime: true" to the page's front matter
 [params.ui.readingtime]
 enable = false
 
 [params.links]
 # End user relevant links. These will show up on left side of footer and in the community page if you have one.
-# [[params.links.user]]
-# 	name = "User mailing list"
-# 	url = "https://example.org/mail"
-# 	icon = "fa fa-envelope"
-#         desc = "Discussion and help from your fellow users"
-# [[params.links.user]]
-# 	name ="Twitter"
-# 	url = "https://example.org/twitter"
-# 	icon = "fab fa-twitter"
-#         desc = "Follow us on Twitter to get the latest news!"
-# [[params.links.user]]
-# 	name = "Stack Overflow"
-# 	url = "https://example.org/stack"
-# 	icon = "fab fa-stack-overflow"
-#         desc = "Practical questions and curated answers"
 # Developer relevant links. These will show up on right side of footer and in the community page if you have one.
 [[params.links.developer]]
-	name = "GitHub"
-	url = "https://github.com/smlx/piv-agent"
-	icon = "fab fa-github"
-        desc = "Development takes place here!"
-# [[params.links.developer]]
-# 	name = "Slack"
-# 	url = "https://example.org/slack"
-# 	icon = "fab fa-slack"
-#         desc = "Chat with other project developers"
-# [[params.links.developer]]
-# 	name = "Developer mailing list"
-# 	url = "https://example.org/mail"
-# 	icon = "fa fa-envelope"
-#         desc = "Discuss development issues around the project"
-# 
+  name = "GitHub"
+  url = "https://github.com/smlx/piv-agent"
+  icon = "fab fa-github"
+  desc = "Development takes place here!"
+
+# hugo module configuration
+
+[module]
+  # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace:
+  # workspace = "docsy.work"
+  [module.hugoVersion]
+    extended = true
+    min = "0.110.0"
+  [[module.imports]]
+    path = "github.com/google/docsy"
+    disable = false

docs/layouts/404.html

@@ -0,0 +1,7 @@
+{{ define "main" -}}
+<div class="td-content">
+  <h1>Not found</h1>
+  <p>Oops! This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">home page</a>.</p>
+  <p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p>
+</div>
+{{- end }}

docs/layouts/_default/_markup/render-heading.html

@@ -0,0 +1 @@
+{{ template "_default/_markup/td-render-heading.html" . }}