dev: new way to fill the documentation #1
Conversation
Co-authored-by: Simon Sawert <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a new approach for managing documentation by replacing Markdown placeholders with Hugo shortcodes and partials that use data files instead of directly modifying Markdown files. This change improves the developer experience by allowing local development without needing to reset changes made by the documentation generation scripts.
Key changes include:
- Replace placeholder-based templating with Hugo shortcodes and data files
- Restructure data generation to create JSON files for dynamic content
- Improve linter/formatter author attribution with better data structures
Reviewed Changes
Copilot reviewed 75 out of 79 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/website/expand_templates/ | Refactored to generate data files instead of modifying Markdown directly |
| scripts/website/dump_info/ | Split into modular functions and updated to output structured JSON data |
| scripts/website/types/types.go | Changed Groups field from map to slice with JSON tags |
| pkg/commands/ | Updated command descriptions with proper punctuation |
| docs/layouts/ | Added Hugo shortcodes and partials for dynamic content rendering |
| docs/data/ | New JSON data files containing linter info, CLI help, and author data |
| docs/content/ | Updated to use new shortcodes instead of placeholders |
| if err != nil { | ||
| return "", fmt.Errorf("can't run help cmd: %w", err) | ||
| } | ||
|
|
There was a problem hiding this comment.
[nitpick] The function returns the full help output including command usage information, but the function name suggests it only returns help text. Consider either renaming the function to getCmdOutput or trimming the output to only include the help text portion for consistency with the original implementation that trimmed the first two lines.
| lines := strings.Split(string(help), "\n") | |
| if len(lines) > 2 { | |
| return strings.Join(lines[2:], "\n"), nil | |
| } |
Copilot uses AI. Check for mistakes.
| document.querySelectorAll('.gl-filter').forEach(element => element.classList.remove(borderClass)); | ||
| }); | ||
| }); | ||
| </script> |
There was a problem hiding this comment.
[nitpick] The JavaScript code is embedded directly in the HTML template. Consider moving this to a separate JavaScript file for better maintainability and separation of concerns.
Copilot uses AI. Check for mistakes.
| var write bool | ||
|
|
||
| // TODO(ldez): use bytes.Lines when min go1.24 (and remove the new line) | ||
| scanner := bufio.NewScanner(bytes.NewBuffer(bytes.ReplaceAll(in, []byte("### "), []byte("## ")))) |
There was a problem hiding this comment.
[nitpick] The hardcoded replacement of ### with ## should be documented or made configurable. This transformation logic is not immediately clear from the function name or context.
| scanner := bufio.NewScanner(bytes.NewBuffer(bytes.ReplaceAll(in, []byte("### "), []byte("## ")))) | |
| scanner := bufio.NewScanner(bytes.NewBuffer(bytes.ReplaceAll( | |
| in, | |
| []byte(changelogHeadingToReplace), | |
| []byte(changelogHeadingReplacement), | |
| ))) |
Copilot uses AI. Check for mistakes.
The previous method for filling data inside the documentation was cumbersome.
It was modifying the Markdown files directly by replacing placeholders with the actual data.
Also, the script to update the documentation was not able to run when the placeholders were already filled.
You were forced to reset the changes made by the script before modifying the files.
But when you modified the same files as the script and reverted the changes, all the changes were reverted.
So it was a pain.
The placeholders are removed from the files; instead, I replaced placeholders with shortcodes and partials that use the data from the dedicated files.
Now, modifying and running locally the documentation is easier.
There is more information about the new way to fill out the documentation on the dedicated page inside the website.
It was not easy to create this new way to fill in the documentation.
The Hugo documentation is complex.
I found bugs inside the theme, and I had to fix them.
There are also a few improvements: