[CI/i18n] Contrib docs update and hugo.yaml config cleanup (#8302)

Author: chalin

.github/copilot-instructions.md

@@ -105,9 +105,9 @@ info here.
 
 ```
 .
-├── README.md              # Project overview and contribution guidelines
-├── package.json           # Node.js dependencies and npm scripts
-├── hugo.yaml             # Hugo configuration with mounts and language settings
+├── README.md             # Project overview and contribution guidelines
+├── package.json          # Node.js dependencies and npm scripts
+├── config/**/*.yaml      # Hugo configuration with mounts and language settings
 ├── content/              # Main content (English and translations)
 ├── content-modules/      # Git submodules for specifications and community docs
 ├── layouts/              # Hugo templates and partial templates
@@ -168,13 +168,14 @@ npm run fix:markdown     # Auto-fix markdown issues
 - Uses Hugo v0.148.2 with extended features
 - Theme: Docsy (Google's documentation theme)
 - Multilingual support enabled for 8+ languages
-- Content mounting from submodules defined in `hugo.yaml`
+- Content mounting from submodules defined in
+  `config/_default/module-template.yaml`
 - Generated files placed in `public/` directory
 
 ### Frequently Accessed Files
 
 - `package.json` - Dependencies and scripts
-- `hugo.yaml` - Site configuration and content mounts
+- `config/_default/*.yaml` - Site configuration and content mounts
 - `content/en/docs/contributing/development.md` - Development setup guide
 - `.warnings-skip-list.txt` - Known acceptable build warnings
 - `.cspell.yml` - Spell checking configuration

.github/localization.instructions.md

@@ -153,7 +153,7 @@ default_lang_commit: <commit-hash-of-english-page>
 
 1. Create issue with localization request
 2. Translate homepage only: `content/LANG_ID/_index.md`
-3. Maintainers will update `hugo.yaml`, cSpell configuration, and create
+3. Maintainers will update Hugo config, cSpell configuration, and create
    language-specific tools
 
 ### Language-Specific Tooling

config/_default/hugo.yaml

@@ -259,251 +259,7 @@ security:
     getenv: # cspell:disable-line
       # Netlify build env var
       - ^(BRANCH|BUILD_ID|COMMIT_REF|CONTEXT|DEPLOY_ID|NETLIFY|PULL_REQUEST|REVIEW_ID)$
-
-module:
-  mounts:
-    ## en
-    - source: content/en
-      target: content
-    - source: tmp/community/mission-vision-values.md
-      target: content/community/mission.md
-    - source: tmp/community/roadmap.md
-      target: content/community/roadmap.md
-    # Specs, currently en only
-    - source: tmp/otel/specification
-      target: content/docs/specs/otel
-    - source: tmp/opamp
-      target: content/docs/specs/opamp
-    - source: tmp/otlp/docs/specification.md
-      target: content/docs/specs/otlp/_index.md
-    - source: tmp/otlp/docs/img
-      target: content/docs/specs/otlp/img
-    # Semconv
-    # cSpell:ignore cloudevents faas
-    - source: tmp/semconv/docs
-      target: content/docs/specs/semconv
-      excludeFiles: '**/README.md'
-    # DO NOT EDIT - semconv autogenerated mounts below - DO NOT EDIT
-    - source: tmp/semconv/docs/app/README.md
-      target: content/docs/specs/semconv/app/_index.md
-    - source: tmp/semconv/docs/azure/README.md
-      target: content/docs/specs/semconv/azure/_index.md
-    - source: tmp/semconv/docs/browser/README.md
-      target: content/docs/specs/semconv/browser/_index.md
-    - source: tmp/semconv/docs/cicd/README.md
-      target: content/docs/specs/semconv/cicd/_index.md
-    - source: tmp/semconv/docs/cli/README.md
-      target: content/docs/specs/semconv/cli/_index.md
-    - source: tmp/semconv/docs/cloud-providers/README.md
-      target: content/docs/specs/semconv/cloud-providers/_index.md
-    - source: tmp/semconv/docs/cloudevents/README.md
-      target: content/docs/specs/semconv/cloudevents/_index.md
-    - source: tmp/semconv/docs/database/README.md
-      target: content/docs/specs/semconv/database/_index.md
-    - source: tmp/semconv/docs/dns/README.md
-      target: content/docs/specs/semconv/dns/_index.md
-    - source: tmp/semconv/docs/dotnet/README.md
-      target: content/docs/specs/semconv/dotnet/_index.md
-    - source: tmp/semconv/docs/exceptions/README.md
-      target: content/docs/specs/semconv/exceptions/_index.md
-    - source: tmp/semconv/docs/faas/README.md
-      target: content/docs/specs/semconv/faas/_index.md
-    - source: tmp/semconv/docs/feature-flags/README.md
-      target: content/docs/specs/semconv/feature-flags/_index.md
-    - source: tmp/semconv/docs/gen-ai/README.md
-      target: content/docs/specs/semconv/gen-ai/_index.md
-    - source: tmp/semconv/docs/general/README.md
-      target: content/docs/specs/semconv/general/_index.md
-    - source: tmp/semconv/docs/graphql/README.md
-      target: content/docs/specs/semconv/graphql/_index.md
-    - source: tmp/semconv/docs/hardware/README.md
-      target: content/docs/specs/semconv/hardware/_index.md
-    - source: tmp/semconv/docs/how-to-write-conventions/README.md
-      target: content/docs/specs/semconv/how-to-write-conventions/_index.md
-    - source: tmp/semconv/docs/http/README.md
-      target: content/docs/specs/semconv/http/_index.md
-    - source: tmp/semconv/docs/messaging/README.md
-      target: content/docs/specs/semconv/messaging/_index.md
-    - source: tmp/semconv/docs/mobile/README.md
-      target: content/docs/specs/semconv/mobile/_index.md
-    - source: tmp/semconv/docs/non-normative/compatibility/README.md
-      target: content/docs/specs/semconv/non-normative/compatibility/_index.md
-    - source: tmp/semconv/docs/non-normative/README.md
-      target: content/docs/specs/semconv/non-normative/_index.md
-    - source: tmp/semconv/docs/object-stores/README.md
-      target: content/docs/specs/semconv/object-stores/_index.md
-    - source: tmp/semconv/docs/otel/README.md
-      target: content/docs/specs/semconv/otel/_index.md
-    - source: tmp/semconv/docs/README.md
-      target: content/docs/specs/semconv/_index.md
-    - source: tmp/semconv/docs/registry/attributes/README.md
-      target: content/docs/specs/semconv/registry/attributes/_index.md
-    - source: tmp/semconv/docs/registry/entities/README.md
-      target: content/docs/specs/semconv/registry/entities/_index.md
-    - source: tmp/semconv/docs/registry/README.md
-      target: content/docs/specs/semconv/registry/_index.md
-    - source: tmp/semconv/docs/resource/cloud-provider/aws/README.md
-      target: content/docs/specs/semconv/resource/cloud-provider/aws/_index.md
-    - source: tmp/semconv/docs/resource/cloud-provider/gcp/README.md
-      target: content/docs/specs/semconv/resource/cloud-provider/gcp/_index.md
-    - source: tmp/semconv/docs/resource/cloud-provider/README.md
-      target: content/docs/specs/semconv/resource/cloud-provider/_index.md
-    - source: tmp/semconv/docs/resource/k8s/README.md
-      target: content/docs/specs/semconv/resource/k8s/_index.md
-    - source: tmp/semconv/docs/resource/README.md
-      target: content/docs/specs/semconv/resource/_index.md
-    - source: tmp/semconv/docs/rpc/README.md
-      target: content/docs/specs/semconv/rpc/_index.md
-    - source: tmp/semconv/docs/runtime/README.md
-      target: content/docs/specs/semconv/runtime/_index.md
-    - source: tmp/semconv/docs/system/README.md
-      target: content/docs/specs/semconv/system/_index.md
-    - source: tmp/semconv/docs/url/README.md
-      target: content/docs/specs/semconv/url/_index.md
-    # DO NOT EDIT - semconv autogenerated mounts above - DO NOT EDIT
-
-    ## bn
-    - source: content/bn
-      target: content
-      lang: bn
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: bn
-    - source: content/en/announcements
-      target: content/announcements
-      lang: bn
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: bn
-
-    ## es
-    - source: content/es
-      target: content
-      lang: es
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: es
-    - source: content/en/announcements
-      target: content/announcements
-      lang: es
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: es
-
-    ## fr
-    - source: content/fr
-      target: content
-      lang: fr
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: fr
-    - source: content/en/announcements
-      target: content/announcements
-      lang: fr
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: fr
-    # - source: content/en/ecosystem
-    #   target: content/ecosystem
-    #   lang: fr
-
-    ## ja
-    - source: content/ja
-      target: content
-      lang: ja
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: ja
-    - source: content/en/announcements
-      target: content/announcements
-      lang: ja
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: ja
-
-    ## ro
-    - source: content/ro
-      target: content
-      lang: ro
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: ro
-    - source: content/en/announcements
-      target: content/announcements
-      lang: ro
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: ro
-
-    ## uk
-    - source: content/uk
-      target: content
-      lang: uk
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: uk
-    - source: content/en/announcements
-      target: content/announcements
-      lang: uk
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: uk
-
-    ## zh
-    - source: content/zh
-      target: content
-      lang: zh
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: zh
-    - source: content/en/announcements
-      target: content/announcements
-      lang: zh
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: zh
-
-    ## pt
-    - source: content/pt
-      target: content
-      lang: pt
-    # fallback pages
-    - source: content/en/_includes
-      target: content/_includes
-      lang: pt
-    - source: content/en/announcements
-      target: content/announcements
-      lang: pt
-    - excludeFiles: specs/*
-      source: content/en/docs
-      target: content/docs
-      lang: pt
-    - source: content/en/ecosystem
-      target: content/ecosystem
-      lang: pt
-
-    ## static
-    - source: static
-      target: static
-    - source: content-modules/semantic-conventions/schemas
-      target: static/schemas
-    - source: static/img
-      target: static/img
-    - source: content-modules/opentelemetry-specification/internal/img
-      target: static/img
-    - source: iconography/32x32
-      target: static/img/logos/32x32
+#
+# mounts: are defined in module-template.yaml. See that file for processing
+# details. For information about Hugo config directories and files, see:
+# https://gohugo.io/configuration/introduction/#configuration-directory.

config/_default/module-template.yaml

@@ -1,3 +1,6 @@
+# This Hugo config `mounts` template is rendered as `module.yaml` and
+# automatically used by Hugo. Also see `hugo.yaml` for other Hugo configuration.
+
 mounts:
   ## en
   - source: content/en
@@ -167,3 +170,6 @@ mounts:
     target: static/img
   - source: iconography/32x32
     target: static/img/logos/32x32
+  ## site
+  - source: config/_default/module.yaml
+    target: static/site/config/module.yaml

content/en/docs/contributing/development.md

@@ -122,12 +122,12 @@ might need to increase the file descriptor limit. See
 The website is built from the following content:
 
 - Files under `content/`, `static/`, etc. per [Hugo] defaults.
-- Mount points, defined in [hugo.yaml] under `mounts`. Mounts are either
-  directly from git submodules under [content-modules], or preprocessed content
-  from `content-modules` (placed under `tmp/`), and no where else.
+- Mount points, defined by Hugo [config] in
+  `config/_default/module-template.yaml`. Mounts are either directly from git
+  submodules under [content-modules], or preprocessed content from
+  `content-modules` (placed under `tmp/`), and no where else.
 
-[hugo.yaml]:
-  https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml
+[config]: https://github.com/open-telemetry/opentelemetry.io/tree/main/config
 [content-modules]:
   https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules
 

content/en/docs/contributing/localization.md

@@ -363,7 +363,7 @@ with the task list given below:
          For details, see
          [Localize the homepage](https://opentelemetry.io/docs/contributing/localization/#homepage).
    - [ ] OTel maintainers:
-     - [ ] Update `hugo.yaml`
+     - [ ] Update Hugo config for `LANG_ID`
      - [ ] Configure cSpell and other tooling support
      - [ ] Create an issue label for `lang:LANG_ID`
      - [ ] Create org-level group for `LANG_ID` approvers
@@ -419,12 +419,12 @@ are easier to review and so typically get merged more quickly.
 
 #### Hugo
 
-Update `hugo.yaml`. Add appropriate entries for `LANG_ID` under:
+Update Hugo config for `LANG_ID`. Add appropriate entries for `LANG_ID` under:
 
-- `languages`
-- `module.mounts`. At a minimum, add a single `source`-`target` entry for
-  `content`. Consider adding entries for `en` fallback pages only once the
-  locale has enough content.
+- `languages` in `config/_default/hugo.yaml`
+- `module.mounts` via `config/_default/module-template.yaml`. At a minimum, add
+  a single `source`-`target` entry for `content`. Consider adding entries for
+  `en` fallback pages only once the locale has enough content.
 
 #### Spelling
 

static/refcache.json

@@ -12351,6 +12351,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-10-25T15:30:05.09591169Z"
   },
+  "https://github.com/open-telemetry/opentelemetry.io/tree/main/config": {
+    "StatusCode": 206,
+    "LastSeen": "2025-10-31T05:56:47.948983-04:00"
+  },
   "https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules": {
     "StatusCode": 206,
     "LastSeen": "2025-10-25T15:30:39.395266003Z"