feat: add markdown output format and LLM-optimized content generation #2484
Conversation
WalkthroughThis pull request introduces comprehensive Markdown output support and LLM-friendly documentation generation to a Hugo-based site. It adds new output format configurations, layout templates for Markdown rendering, extensive shortcode implementations for both HTML and Markdown outputs, specialized sitemaps for Markdown and LLM consumption, and updated crawler rules. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Hugo
participant Config
participant Layouts
participant Output
User->>Hugo: Build site with config.toml
Hugo->>Config: Read output formats<br/>(HTML, MARKDOWN, LLMSFULL, SITEMAPMD)
rect rgb(200, 220, 255)
Note over Hugo,Output: Render Page
Hugo->>Layouts: Select layout based format
alt Output = MARKDOWN
Layouts->>Output: Render _default/single.md<br/>(frontmatter + shortcodes)
else Output = LLMSFULL
Layouts->>Output: Render index.llmsfull.txt<br/>(TOC + full content)
else Output = HTML
Layouts->>Output: Render standard HTML layout
end
end
rect rgb(220, 255, 220)
Note over Hugo,Output: Sitemap Generation
Hugo->>Layouts: Generate sitemaps
Layouts->>Output: sitemap.xml<br/>(HTML + MARKDOWN URLs)
Layouts->>Output: index.sitemapmd.xml<br/>(MARKDOWN URLs only)
end
Output->>User: Multi-format output<br/>(HTML, MD, LLM-friendly)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
According to this discussion, a robots.txt file in the root will be served by Github Pages. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (5)
themes/hugo-theme-altinn/layouts/shortcodes/panel.markdown (1)
14-14: Minor whitespace artifact when icon is absent.When
$themeis "primary" (the default), the{{ $icon }}variable is empty, but line 14 will still output a leading space before**header**:**header**. While this typically renders correctly in Markdown parsers, it's cleaner to avoid unnecessary whitespace.Consider conditionally including the space only when an icon is present:
-{{ with .Get "header" }}{{ $icon }} **{{ htmlUnescape . }}** +{{ with .Get "header" -}} + {{- if $icon }}{{ $icon }} {{ end -}} + **{{ htmlUnescape . }}**themes/hugo-theme-altinn/layouts/shortcodes/swaggerload.markdown (1)
2-2: Consider emoji usage consistency for LLM-optimized content.The emoji (📋) on this line provides visual distinction but differs from other Swagger shortcodes. While emoji rendering is generally reliable in Markdown, consider whether this styling is appropriate and consistent with the LLM-optimized content generation goals of this PR.
themes/hugo-theme-altinn/layouts/shortcodes/notyetwritten.markdown (1)
2-2: Add punctuation and refine English phrasing.The Norwegian and English introductory lines lack ending punctuation, which may appear incomplete. Additionally, the English phrasing "on the bottom of this page" should be "at the bottom of this page" for clarity.
Suggested changes:
- 🚧 **Denne delen er ufullstendig** + 🚧 **Denne delen er ufullstendig.** - 🚧 **This section is incomplete** + 🚧 **This section is incomplete.**And later in the English section:
- While we're working on it, contributions are also very welcome. Hit "Edit this page on GitHub" on the bottom of this page to get started. + While we're working on it, contributions are also very welcome. Hit "Edit this page on GitHub" at the bottom of this page to get started.Also applies to: 6-6
layouts/index.llmsfull.txt (1)
60-63: Capitalize "Markdown" as a proper noun.Lines 60 and 63 use lowercase "markdown" but should use the proper noun "Markdown" to align with AP style and trademark conventions.
- This file is automatically generated by Hugo and contains all public documentation pages from docs.altinn.studio. Content is provided in markdown format for optimal processing by Large Language Models. + This file is automatically generated by Hugo and contains all public documentation pages from docs.altinn.studio. Content is provided in Markdown format for optimal processing by Large Language Models. - For the curated, navigational version of this documentation, see llms.txt. - For individual pages in markdown format, append /index.md to any documentation URL. + For the curated, navigational version of this documentation, see llms.txt. + For individual pages in Markdown format, append /index.md to any documentation URL.themes/hugo-theme-altinn/layouts/shortcodes/insert.markdown (1)
1-7: Stylistic: Use typographical ellipsis in comments.The inline documentation uses
...for ellipses in lines 3 and 6. Consider using the proper Unicode ellipsis character (…) for better typography consistency.Example:
-Placeholders must use format {0}, {1}... {n} +Placeholders must use format {0}, {1}… {n}-{{% insert [full file path] [variable 0]... [variable n]" %}} +{{% insert [full file path] [variable 0]… [variable n]" %}}As per LanguageTool hints.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (38)
config.toml(1 hunks)layouts/_default/list.md(1 hunks)layouts/_default/single.md(1 hunks)layouts/index.llmsfull.txt(1 hunks)layouts/index.sitemapmd.xml(1 hunks)layouts/partials/custom-head.html(1 hunks)layouts/partials/markdown-alternate.html(1 hunks)layouts/shortcodes/expand.html(1 hunks)layouts/shortcodes/expandlarge.html(1 hunks)layouts/shortcodes/notice.html(1 hunks)layouts/sitemap-markdown.xml(1 hunks)layouts/sitemap.xml(1 hunks)static/robots.txt(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/center.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/children.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/code-title.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/content-version-container.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/content-version-selector.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/dialogportenswaggerselector.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/displayFootnotes.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/excerpt.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/expand.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/expandlarge.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/expandsmall.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/info.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/insert.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/link.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/mermaid.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/notice.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/notyetwritten.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/panel.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/swaggerdisplayentity.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/swaggerdisplayoperation.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/swaggerload.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/tip.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/title.markdown(1 hunks)themes/hugo-theme-altinn/layouts/shortcodes/warning.markdown(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
layouts/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
layouts/index.sitemapmd.xmllayouts/_default/single.mdlayouts/index.llmsfull.txtlayouts/sitemap.xmllayouts/_default/list.mdlayouts/shortcodes/expandlarge.htmllayouts/shortcodes/notice.htmllayouts/partials/custom-head.htmllayouts/partials/markdown-alternate.htmllayouts/sitemap-markdown.xmllayouts/shortcodes/expand.html
static/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
static/robots.txt
*.toml
⚙️ CodeRabbit configuration file
Check syntax.
Files:
config.toml
🧠 Learnings (1)
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
PR: Altinn/altinn-studio-docs#2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
themes/hugo-theme-altinn/layouts/shortcodes/swaggerload.markdown
🪛 LanguageTool
themes/hugo-theme-altinn/layouts/shortcodes/insert.markdown
[style] ~3-~3: Consider using the typographical ellipsis character here instead.
Context: .... Placeholders must use format {0}, {1}... {n} Usage: {{% insert [full file pat...
(ELLIPSIS)
[style] ~6-~6: Consider using the typographical ellipsis character here instead.
Context: ...{{% insert [full file path] [variable 0]... [variable n]" %}} */}} {{ $filePath :...
(ELLIPSIS)
themes/hugo-theme-altinn/layouts/shortcodes/expand.markdown
[style] ~4-~4: Consider using the typographical ellipsis character here instead.
Context: ...le = .Get "default" | default "Expand me..." -}} {{- else -}} {{- $title = .Get 0...
(ELLIPSIS)
[style] ~6-~6: Consider using the typographical ellipsis character here instead.
Context: ...{{- $title = .Get 0 | default "Expand me..." -}} {{- end -}}
{{...
(ELLIPSIS)
layouts/index.llmsfull.txt
[uncategorized] ~60-~60: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...s.altinn.studio. Content is provided in markdown format for optimal processing by Large ...
(MARKDOWN_NNP)
[uncategorized] ~63-~63: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ..., see llms.txt. For individual pages in markdown format, append /index.md to any documen...
(MARKDOWN_NNP)
static/robots.txt
[grammar] ~10-~10: Please add a punctuation mark at the end of paragraph.
Context: ... /swagger/ Disallow: /*sitemap-markdown.xml # Sitemap for traditional search engin...
(PUNCTUATION_PARAGRAPH_END)
themes/hugo-theme-altinn/layouts/shortcodes/mermaid.markdown
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: mermaid {{ .Inner }}
(QB_NEW_DE)
themes/hugo-theme-altinn/layouts/shortcodes/code-title.markdown
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: {{- .Inner -}}
(QB_NEW_DE)
themes/hugo-theme-altinn/layouts/shortcodes/title.markdown
[uncategorized] ~1-~1: Ne zlefe ket bezañ ur c’hemmadur dre vlotaat amañ.
Context: {{ .Page.Title }}
(FAZ_KEMM)
themes/hugo-theme-altinn/layouts/shortcodes/notyetwritten.markdown
[grammar] ~2-~2: Please add a punctuation mark at the end of paragraph.
Context: ... .Page.Lang "nb" }} 🚧 Denne delen er ufullstendig Vi jobber med saken, men dine bidrag...
(PUNCTUATION_PARAGRAPH_END)
🪛 markdownlint-cli2 (0.18.1)
themes/hugo-theme-altinn/layouts/shortcodes/children.markdown
9-9: Hard tabs
Column: 1
(MD010, no-hard-tabs)
10-10: Hard tabs
Column: 1
(MD010, no-hard-tabs)
11-11: Hard tabs
Column: 1
(MD010, no-hard-tabs)
23-23: Hard tabs
Column: 1
(MD010, no-hard-tabs)
25-25: Hard tabs
Column: 1
(MD010, no-hard-tabs)
27-27: Hard tabs
Column: 1
(MD010, no-hard-tabs)
29-29: Hard tabs
Column: 1
(MD010, no-hard-tabs)
31-31: Hard tabs
Column: 1
(MD010, no-hard-tabs)
33-33: Hard tabs
Column: 1
(MD010, no-hard-tabs)
35-35: Hard tabs
Column: 1
(MD010, no-hard-tabs)
41-41: Hard tabs
Column: 1
(MD010, no-hard-tabs)
42-42: Hard tabs
Column: 1
(MD010, no-hard-tabs)
43-43: Hard tabs
Column: 1
(MD010, no-hard-tabs)
48-48: Hard tabs
Column: 1
(MD010, no-hard-tabs)
49-49: Hard tabs
Column: 1
(MD010, no-hard-tabs)
50-50: Hard tabs
Column: 1
(MD010, no-hard-tabs)
51-51: Hard tabs
Column: 1
(MD010, no-hard-tabs)
52-52: Hard tabs
Column: 1
(MD010, no-hard-tabs)
53-53: Hard tabs
Column: 1
(MD010, no-hard-tabs)
55-55: Hard tabs
Column: 1
(MD010, no-hard-tabs)
56-56: Hard tabs
Column: 1
(MD010, no-hard-tabs)
57-57: Hard tabs
Column: 1
(MD010, no-hard-tabs)
58-58: Hard tabs
Column: 1
(MD010, no-hard-tabs)
59-59: Hard tabs
Column: 1
(MD010, no-hard-tabs)
60-60: Hard tabs
Column: 1
(MD010, no-hard-tabs)
61-61: Hard tabs
Column: 1
(MD010, no-hard-tabs)
62-62: Hard tabs
Column: 1
(MD010, no-hard-tabs)
63-63: Hard tabs
Column: 1
(MD010, no-hard-tabs)
64-64: Hard tabs
Column: 1
(MD010, no-hard-tabs)
65-65: Hard tabs
Column: 1
(MD010, no-hard-tabs)
66-66: Hard tabs
Column: 1
(MD010, no-hard-tabs)
67-67: Hard tabs
Column: 1
(MD010, no-hard-tabs)
68-68: Hard tabs
Column: 1
(MD010, no-hard-tabs)
69-69: Hard tabs
Column: 1
(MD010, no-hard-tabs)
70-70: Hard tabs
Column: 1
(MD010, no-hard-tabs)
71-71: Hard tabs
Column: 1
(MD010, no-hard-tabs)
72-72: Hard tabs
Column: 1
(MD010, no-hard-tabs)
themes/hugo-theme-altinn/layouts/shortcodes/excerpt.markdown
2-2: Hard tabs
Column: 1
(MD010, no-hard-tabs)
3-3: Hard tabs
Column: 1
(MD010, no-hard-tabs)
4-4: Hard tabs
Column: 1
(MD010, no-hard-tabs)
6-6: Hard tabs
Column: 1
(MD010, no-hard-tabs)
themes/hugo-theme-altinn/layouts/shortcodes/swaggerdisplayoperation.markdown
1-1: Spaces inside emphasis markers
(MD037, no-space-in-emphasis)
1-1: Spaces inside emphasis markers
(MD037, no-space-in-emphasis)
🔇 Additional comments (42)
themes/hugo-theme-altinn/layouts/shortcodes/content-version-selector.markdown (1)
1-2: Clean pass-through implementation for markdown output.The shortcode correctly renders inner content for markdown output without UI elements. The implementation is simple, direct, and aligns with the PR's goal of LLM-friendly content generation.
themes/hugo-theme-altinn/layouts/shortcodes/code-title.markdown (1)
1-1: Verify intended behavior: doescode-titleneed Markdown-specific formatting?This shortcode simply passes through inner content without adding any Markdown formatting or structure. For a shortcode named
code-title, consider whether it should:
- Wrap the title in Markdown code formatting (e.g., backticks)
- Add additional Markdown semantics (e.g., bold, headings)
- Include the title as a comment or metadata line
Please confirm this minimal passthrough behavior is intentional and aligns with how other new Markdown shortcodes in this PR (e.g.,
notice,expand,panel) handle their content.Note: LanguageTool's static analysis flag is a false positive—it incorrectly detected German grammar in the Hugo template syntax and can be safely ignored.
themes/hugo-theme-altinn/layouts/shortcodes/panel.markdown (1)
1-22: Verify language-specific documentation.Per tone instructions, documentation should be available in English (en-US), Norwegian Bokmål (nb-NO), and Norwegian Nynorsk (nn-NO). Please confirm that this shortcode has corresponding documentation or comments in all three language variants, particularly if user-facing help text or descriptions are expected.
themes/hugo-theme-altinn/layouts/shortcodes/dialogportenswaggerselector.markdown (1)
1-6: Missing Norwegian translations (nb-NO, nn-NO).The tone instructions explicitly request documentation review in English (en-US), Norwegian Bokmål (nb-NO), and Norwegian Nynorsk (nn-NO). This shortcode contains English-only content. Please clarify whether multilingual translations are required for this PR or out of scope.
themes/hugo-theme-altinn/layouts/shortcodes/swaggerdisplayoperation.markdown (2)
1-1: Verify static analysis linting issue (MD037).Markdownlint flagged a potential MD037 issue (spaces inside emphasis markers) on this line. The flag likely refers to the comment syntax (
/*and*/) being misconstrued as emphasis markers. Please verify that the linting issue is a false positive or apply a fix if necessary.
1-4: Missing Norwegian translations (nb-NO, nn-NO).The tone instructions explicitly request documentation review in English (en-US), Norwegian Bokmål (nb-NO), and Norwegian Nynorsk (nn-NO). This shortcode contains English-only content. Please clarify whether multilingual translations are required for this PR or out of scope.
themes/hugo-theme-altinn/layouts/shortcodes/swaggerdisplayentity.markdown (1)
1-4: Missing Norwegian translations (nb-NO, nn-NO).The tone instructions explicitly request documentation review in English (en-US), Norwegian Bokmål (nb-NO), and Norwegian Nynorsk (nn-NO). This shortcode contains English-only content. Please clarify whether multilingual translations are required for this PR or out of scope.
themes/hugo-theme-altinn/layouts/shortcodes/swaggerload.markdown (1)
1-4: Missing Norwegian translations (nb-NO, nn-NO).The tone instructions explicitly request documentation review in English (en-US), Norwegian Bokmål (nb-NO), and Norwegian Nynorsk (nn-NO). This shortcode contains English-only content. Please clarify whether multilingual translations are required for this PR or out of scope.
themes/hugo-theme-altinn/layouts/shortcodes/content-version-container.markdown (1)
1-5: I need to verify the review comment's core concern about Hugo whitespace handling. Let me gather information:Now let me search for information about Hugo's RenderString method to understand its behavior better:Now let me check the repository for similar shortcode patterns to see if there's an established convention:
Remove the blank line to prevent unintended Markdown formatting.
Blank lines in Hugo template files create extra whitespace that causes formatting issues. Removing this empty line will fix the problem. In this shortcode, having everything on one line makes the template functional, though potentially less readable. Alternatively, use Hugo's whitespace control syntax ({{- and -}}) to preserve readability while preventing extra output.
The current template:
{{/* For markdown output, just render the inner content without the UI container */}} {{ with .Get "version-label" }}**{{ . }}** {{ end }} {{.Inner | .Page.RenderString }}Should be changed to remove the blank line between the version-label output and the conditional closure to ensure clean Markdown output.
themes/hugo-theme-altinn/layouts/shortcodes/warning.markdown (1)
1-7: Clean and consistent shortcode implementation.The warning shortcode follows an established pattern for conditional title rendering and properly applies htmlUnescape and trimming. Well done.
themes/hugo-theme-altinn/layouts/shortcodes/notice.markdown (1)
1-13: Well-structured type-based rendering.Clear emoji mapping and consistent templating. The default "info" type and title-cased labels provide good UX consistency.
layouts/shortcodes/notice.html (1)
1-1: Solid shortcode implementation with proper conditional logic.The dynamic class and conditional id handling is correct. Good use of RenderString for nested content.
themes/hugo-theme-altinn/layouts/shortcodes/tip.markdown (1)
1-7: Consistent with established shortcode patterns.Good symmetry with the warning shortcode. Clean conditional logic for title parameter.
themes/hugo-theme-altinn/layouts/shortcodes/expandsmall.markdown (1)
1-9: Well-structured collapsible shortcode.The details/summary pattern is semantically correct, and the header parameter with sensible default provides flexibility. RenderString usage is appropriate for nested content.
themes/hugo-theme-altinn/layouts/shortcodes/info.markdown (1)
1-7: Consistent and well-executed.Clean implementation following the established title-conditional pattern. Good emoji choice and default labeling.
layouts/shortcodes/expandlarge.html (1)
13-13: Verify localization strategy for hardcoded UI text.The screen reader text "Vis/skjul innhold" (Norwegian Bokmål) is hardcoded without i18n wrapping, while the fallback header text "expand-default" (line 18) remains English. Ensure this aligns with your site's localization approach, or wrap both in language-appropriate i18n functions.
static/robots.txt (1)
81-95: Verify crawler configuration completeness.The robots.txt defines Sitemap directives for the first set of AI crawlers (GPTBot through Applebot-Extended, lines 19–79) but omits them for the final four (Bytespider, ImagesiftBot, Omgilibot, Omgili). Confirm whether this omission is intentional—if these crawlers should also access markdown content, add the markdown sitemap URLs for consistency.
themes/hugo-theme-altinn/layouts/shortcodes/title.markdown (1)
1-1: LGTM!Straightforward shortcode that outputs the page title; the static analysis hint is a false positive on template syntax and can be safely ignored.
themes/hugo-theme-altinn/layouts/shortcodes/mermaid.markdown (1)
1-3: LGTM!Properly structured markdown code fence for mermaid diagrams; the static analysis hint is a false positive on template syntax.
layouts/_default/list.md (1)
1-16: LGTM!Front matter generation is well-structured with proper YAML syntax, correct Hugo template functions, and sound param filtering logic. Date format string is correct for Go's time package.
themes/hugo-theme-altinn/layouts/shortcodes/center.markdown (1)
1-2: LGTM!Clear comment explaining the markdown passthrough behavior, and the implementation is correct. Aligns well with the markdown-centric output strategy.
layouts/partials/markdown-alternate.html (1)
1-5: LGTM!Partial correctly iterates over alternative formats, filters for MARKDOWN, and renders a properly structured alternate link. English text is clear.
layouts/_default/single.md (1)
1-16: LGTM!Consistent with list.md layout; proper YAML front matter generation, correct Hugo template functions, and sound param filtering. Date format and conditional logic are correct.
config.toml (1)
65-88: LGTM!TOML syntax is valid across all output format definitions and output mappings. Configuration properly establishes three new output formats (MD, LLMSFULL, SITEMAPMD) with appropriate media types, basenames, and flags.
layouts/sitemap-markdown.xml (2)
1-30: LGTM!Well-structured XML sitemap template with correct conditional logic, proper Hugo template syntax, and appropriate optional element handling. URL generation correctly appends "index.md" for markdown files, and date formatting follows Go conventions.
1-30: Note: robots.txt implementation not found in provided files.The PR description mentions serving markdown to AI crawlers via robots.txt configuration, but a robots.txt file was not included in this review set. Verify that robots.txt has been added to the repository root (as mentioned in the PR comment that GitHub Pages will serve it) to complete the crawler routing strategy.
layouts/index.sitemapmd.xml (3)
1-6: XML structure and filtering logic look good.The template correctly declares the XML sitemap format and filters out private pages and pages without permalinks.
7-8: Verify markdown URL construction pattern.Line 7 appends "index.md" directly to
.Permalink. This assumes markdown content is served at{.Permalink}index.md. Confirm this matches how the markdown output format is actually configured and served in this Hugo setup.
8-16: Optional fields rendered correctly.The conditional rendering of lastmod, changefreq, and priority follows the standard sitemap schema and proper Hugo template syntax.
layouts/sitemap.xml (3)
1-3: XML namespaces correctly configured.The xhtml namespace is appropriately included to support alternate link references for HTML and Markdown variants.
5-19: HTML version URL entries correctly structured.The HTML variant follows standard sitemap format with appropriate conditional rendering of optional fields.
20-36: Markdown variant generation strategy is sound.The approach of iterating AlternativeOutputFormats and creating separate URL entries for MARKDOWN variants is appropriate. The use of
$for root context attributes and.for format-specific attributes is correct. Once the line 32 context bug is fixed, this section should work as intended.themes/hugo-theme-altinn/layouts/shortcodes/link.markdown (4)
6-12: Usage examples are clear and well-documented.The examples effectively demonstrate all supported attributes with clear notation of the default behavior.
15-20: Path resolution logic is sound.The use of
path.Join,path.Clean, andsite.GetPagecorrectly resolves relative paths to absolute page references.
22-37: Display text selection and error handling are well-implemented.The if/else logic correctly maps attributes to page properties, with appropriate error messages and a fallback for invalid attributes. Using
RelPermalinkfor markdown links and checking for non-empty text before output are good practices.
38-40: Missing page error handling is appropriate.The shortcode correctly detects missing pages and provides an informative error message that includes the attempted path, which will help users debug configuration issues.
themes/hugo-theme-altinn/layouts/shortcodes/insert.markdown (2)
19-21: LGTM: Content extraction logic is sound.The front matter extraction approach (splitting by "---" and taking the last segment) correctly handles Hugo front matter. The placeholder offset logic (subtracting 1 from parameter index) properly accounts for the file path parameter.
11-31: The shortcode's global replacement behavior is intentional and documented.The inline comments at the top of
insert.markdownexplicitly state: "Following parameters will be replaces based on a 0-index. Placeholders must use format {0}, {1}... {n}." This confirms that replacing all occurrences of each placeholder is the designed behavior—each parameter globally replaces its corresponding placeholder ({0}, {1}, etc.) throughout the included file.The actual usages in the codebase (found across en-US and nb-NO files) support this design, with calls passing 0–1 parameters as simple replacement values (e.g., "notifications", "Notifications"). No evidence of repeated placeholders requiring selective replacement was found.
If replacing only the first occurrence of a placeholder is needed, line 25 can be updated to use Hugo's optional limit parameter:
{{ $content = replace $content (printf "{%d}" (sub $index 1)) $param 1 }}.themes/hugo-theme-altinn/layouts/shortcodes/displayFootnotes.markdown (1)
1-14: LGTM: Footnote rendering and state management logic is correct.The shortcode correctly implements the footnote display workflow: rendering collected footnotes in proper Markdown format, supporting optional state reset, and providing helpful error guidance. The "noreset" escape hatch is a sensible design for use cases requiring persistent footnote state across content sections.
themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown (3)
1-12: LGTM: Usage documentation is clear and accurate.The comment block clearly explains the two-step workflow: collecting footnotes via repeated
footnoteshortcodes and rendering them viadisplayFootnotes. The pattern is intuitive and well-documented.
14-23: LGTM: Footnote collection and reference system is well-designed.The implementation correctly:
- Initializes scratch state only once per page (idempotent)
- Increments index with each call, starting from 1
- Stores footnotes in a mergeable dictionary structure
- Outputs standard Markdown footnote reference syntax without trailing whitespace
The approach of collecting footnotes during rendering and deferring output to a separate
displayFootnotescall is a solid pattern for Markdown generation, allowing flexible footnote placement.
19-20: I'll verify the actual usage patterns and documentation around the footnote implementation.I need to investigate whether the out-of-order rendering issue Hugo documentation mentions could affect this footnote implementation:
Let me check the Hugo version requirement and look for any documentation in the shortcode files themselves:
The footnote index uniqueness concern is unfounded for modern Hugo versions.
Based on my verification:
Shortcodes are processed and rendered in their order of appearance since Hugo v0.40, which resolves the theoretical rendering-order issue that could have caused index collisions in older versions.
The implementation is sound:
- Page scratch is scoped to the current page, eliminating cross-page collisions
- Index initializes once per page and increments monotonically with each footnote call
- The optional reset mechanism in
displayFootnoteshandles section-specific numbering if neededThe code from lines 19-20 correctly maintains unique indices across a single page render. There are no collision scenarios present, and the current implementation requires no changes.
| {{ if ge $.Sitemap.Priority 0.0 }} | ||
| <priority>{{ . }}</priority> | ||
| {{ end }} |
There was a problem hiding this comment.
Critical: Incorrect variable reference for priority value.
Line 32 uses {{ . }} which refers to the current AlternativeOutputFormats item (from line 21's range), not the Sitemap.Priority value. The with block on line 28 only affects lines 28-29 and ends at line 30, so . reverts to the format item afterward.
Apply this fix:
{{ if ge $.Sitemap.Priority 0.0 }}
- <priority>{{ . }}</priority>
+ <priority>{{ $.Sitemap.Priority }}</priority>
{{ end }}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {{ if ge $.Sitemap.Priority 0.0 }} | |
| <priority>{{ . }}</priority> | |
| {{ end }} | |
| {{ if ge $.Sitemap.Priority 0.0 }} | |
| <priority>{{ $.Sitemap.Priority }}</priority> | |
| {{ end }} |
🤖 Prompt for AI Agents
In layouts/sitemap.xml around lines 31 to 33, the template incorrectly uses {{ .
}} for the priority value (which refers to the current AlternativeOutputFormats
item) — replace that with the global sitemap priority reference (e.g. {{
$.Sitemap.Priority }}) so the priority prints the actual Sitemap.Priority value;
ensure you remove the stray {{ . }} and use the absolute variable
$.Sitemap.Priority (optionally format with printf if a specific decimal format
is required).
| {{ if not (eq (.Get 0) "noreset") }} | ||
| {{ .Page.Scratch.Set "footnotes" (dict) }} | ||
| {{ .Page.Scratch.Set "footnoteIndex" 0 }} | ||
| {{ .Page.Scratch.Set "footnotesInitialized" false }} | ||
| {{ end }} |
There was a problem hiding this comment.
🧩 Analysis chain
Note: Reset state assumption.
The reset logic assumes that calling displayFootnotes will clear footnote state for subsequent content. Ensure that content authors understand this behavior and know they can pass "noreset" to retain state across multiple display calls. Consider adding this to the referenced footnote.markdown documentation if not already present.
Verify the footnote.markdown file contains guidance on when to use "noreset":
🏁 Script executed:
#!/bin/bash
# Check if footnote.markdown documents the noreset behavior
cat themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown | grep -A 5 -B 5 "noreset"Length of output: 0
---
🏁 Script executed:
```shell
#!/bin/bash
# Check if footnote.markdown exists and explore the shortcodes directory structure
echo "=== Checking shortcodes directory structure ==="
find themes/hugo-theme-altinn/layouts/shortcodes -type f -name "*footnote*" 2>/dev/null || echo "No footnote files found"
echo ""
echo "=== Searching for all shortcode files ==="
ls -la themes/hugo-theme-altinn/layouts/shortcodes/ 2>/dev/null || echo "Directory not found"
echo ""
echo "=== Searching for 'noreset' anywhere in shortcodes ==="
grep -r "noreset" themes/hugo-theme-altinn/layouts/shortcodes/ 2>/dev/null || echo "No noreset references found"
echo ""
echo "=== Checking for language-specific documentation directories ==="
find themes/hugo-theme-altinn -type d -name "*nb-NO*" -o -name "*nn-NO*" -o -name "*en-US*" 2>/dev/null | head -20
Length of output: 5868
🏁 Script executed:
#!/bin/bash
# Check the actual content of footnote.markdown
echo "=== Content of footnote.markdown ==="
cat themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown
echo ""
echo "=== Content of footnote.html ==="
cat themes/hugo-theme-altinn/layouts/shortcodes/footnote.html
echo ""
echo "=== Content of displayFootnotes.markdown ==="
cat themes/hugo-theme-altinn/layouts/shortcodes/displayFootnotes.markdownLength of output: 2600
🏁 Script executed:
#!/bin/bash
# Search for language-specific content or documentation directories
echo "=== Searching for language-specific directories in content ==="
find . -type d \( -name "*nb-NO*" -o -name "*nn-NO*" -o -name "*en-US*" \) 2>/dev/null | head -20
echo ""
echo "=== Checking content directory structure ==="
ls -d content/*/ 2>/dev/null | head -20 || echo "No language dirs found"
echo ""
echo "=== Searching for footnote documentation in content ==="
find . -type f -name "*footnote*" ! -path "*/\.git/*" 2>/dev/null | grep -v node_modulesLength of output: 297
Add "noreset" parameter documentation to footnote.markdown.
The verification confirms a documentation gap: while footnote.html documents the "noreset" behavior ("This will also reset the counter, unless "noreset" is supplied as a parameter"), footnote.markdown lacks this guidance. Since displayFootnotes.markdown directs users to footnote.markdown for usage information, content authors will miss the "noreset" option.
Update themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown to include:
- When to use "noreset" (to retain footnote state across multiple display calls)
- Example usage pattern showing both normal reset and "noreset" scenarios
🤖 Prompt for AI Agents
In themes/hugo-theme-altinn/layouts/shortcodes/footnote.markdown (add near the
top or the existing usage section), add documentation for the "noreset"
parameter: explain that by default the footnote counter and stored footnotes are
reset on each display call, but passing "noreset" preserves footnote state
across multiple displayFootnotes calls so you can accumulate footnotes across
separate sections; include a short example snippet showing the normal reset case
and a second example showing displayFootnotes with "noreset" to retain the
counter and notes; keep language concise and mirror the wording used in
footnote.html so users directed from displayFootnotes.markdown see the same
guidance.
| {{with .Get "hidden"}} | ||
| {{if eq . "false"}} | ||
| {{$.Inner}} | ||
| {{end}} | ||
| {{else}} | ||
| {{.Inner}} | ||
| {{end}} |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Replace hard tabs with spaces for consistency and linting compliance.
Markdownlint flags hard tabs on lines 2, 3, 4, and 6. While Hugo templates tolerate hard tabs, replacing them with spaces improves consistency across the codebase and resolves linting warnings.
Apply this diff:
{{with .Get "hidden"}}
- {{if eq . "false"}}
- {{$.Inner}}
- {{end}}
+ {{if eq . "false"}}
+ {{$.Inner}}
+ {{end}}
{{else}}
- {{.Inner}}
+ {{.Inner}}
{{end}}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {{with .Get "hidden"}} | |
| {{if eq . "false"}} | |
| {{$.Inner}} | |
| {{end}} | |
| {{else}} | |
| {{.Inner}} | |
| {{end}} | |
| {{with .Get "hidden"}} | |
| {{if eq . "false"}} | |
| {{$.Inner}} | |
| {{end}} | |
| {{else}} | |
| {{.Inner}} | |
| {{end}} |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
2-2: Hard tabs
Column: 1
(MD010, no-hard-tabs)
3-3: Hard tabs
Column: 1
(MD010, no-hard-tabs)
4-4: Hard tabs
Column: 1
(MD010, no-hard-tabs)
6-6: Hard tabs
Column: 1
(MD010, no-hard-tabs)
🤖 Prompt for AI Agents
In themes/hugo-theme-altinn/layouts/shortcodes/excerpt.markdown around lines 1
to 7, replace the hard tab characters on lines 2, 3, 4, and 6 with spaces (use 2
or 4 spaces per tab according to project convention; if unknown, use 4 spaces)
so the template content remains identical but no tabs remain; save and re-run
markdownlint to confirm the warnings are resolved.
| @@ -0,0 +1,40 @@ | |||
| {{/* | |||
|
|
|||
| This short code allows making anchor links to other pages using that page description, title or linkTitle | |||
There was a problem hiding this comment.
Fix terminology: "short code" → "shortcode".
Line 3 uses "short code" (two words) but the correct Hugo term is "shortcode" (one word).
Apply this fix:
-This short code allows making anchor links to other pages using that page description, title or linkTitle
+This shortcode allows making anchor links to other pages using that page description, title or linkTitle📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| This short code allows making anchor links to other pages using that page description, title or linkTitle | |
| This shortcode allows making anchor links to other pages using that page description, title or linkTitle |
🤖 Prompt for AI Agents
themes/hugo-theme-altinn/layouts/shortcodes/link.markdown around line 3: change
the phrase "short code" to the correct Hugo term "shortcode" (single word) so
the description reads "...This shortcode allows making anchor links..." and
update any other occurrences in this file to use "shortcode" consistently.
1 participant
Uses
robots.txtto serve Markdown content to AI crawlers, continuing to serve HTML content to traditional search engine crawlers.Summary by CodeRabbit
Release Notes
New Features
Documentation