guides: remove duplicate config files - #2360
Conversation
Many of the Guides pages have example config files in the content/docs/examples/guides folder. Most of these have both .yaml and .yaml.md versions of the config. The plain .yaml files are used in automated tests, while the .yaml.md files are the ones actually included in the site source. This opens up the possibility that the tested configurations could drift out of sync with the rendered guides. Instead, let's use the webpack "raw loader" to include the plain .yaml files in the guide pages directly, using explicit <CodeBlock> components instead of the Markdown backtick fences (```). Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Greptile SummaryThis PR removes duplicated fenced YAML mirrors and changes 15 guide pages to render the tested plain YAML fixtures directly through Docusaurus CodeBlock components. The consolidation prevents displayed examples from drifting from tested fixtures, but the new resource paths are filesystem-absolute and therefore prevent the migrated pages from compiling.
Confidence Score: 4/5The PR is not safe to merge until the raw-loader resource paths are made repository-relative, because the migrated guide pages cannot compile as written. All 15 changed guides pass filesystem-absolute Files Needing Attention: All changed files under content/docs/guides/, especially content/docs/guides/ad-guard.mdx and content/docs/guides/jit.mdx
|
| Filename | Overview |
|---|---|
| content/docs/guides/ad-guard.mdx | Migrates both examples to raw-loader, but the /content/... resource paths resolve outside the repository and break compilation. |
| content/docs/guides/jit.mdx | Migrates the Compose example using the same unresolved filesystem-absolute raw-loader path. |
| content/docs/guides/forgejo.mdx | Preserves the guide content while adopting the same build-breaking raw-loader path pattern. |
| content/docs/guides/transmission.mdx | Uses CodeBlock correctly, but both newly imported YAML resources require the @site alias or relative paths. |
Reviews (1): Last reviewed commit: "guides: remove duplicate config files" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| import Config from '!!raw-loader!/content/examples/guides/ad-guard/config.yaml'; | ||
| import Compose from '!!raw-loader!/content/examples/guides/ad-guard/docker-compose.yaml'; |
There was a problem hiding this comment.
These raw-loader requests use /content/... as the resource path. After the ! separator, webpack treats the leading slash as a filesystem-absolute path, so it looks outside the repository for /content/examples/.... The repository's working raw-loader imports instead use @site/content/... or relative paths. As a result, the migrated guides cannot resolve these modules during MDX compilation. The same pattern appears in all 15 changed guide pages; use @site/content/... for each resource.
Red test proving the current paths do not resolve:
import assert from 'node:assert/strict';
import { existsSync } from 'node:fs';
import test from 'node:test';
const imports = [
'!!raw-loader!/content/examples/guides/ad-guard/config.yaml',
'!!raw-loader!/content/examples/guides/ad-guard/docker-compose.yaml',
];
test('raw-loader resource paths resolve', () => {
for (const request of imports) {
const resource = request.slice(request.lastIndexOf('!') + 1);
assert.ok(existsSync(resource), `webpack resource does not exist: ${resource}`);
}
});This test is red because /content/examples/guides/ad-guard/config.yaml does not exist at the filesystem root; the retained file is beneath the repository root.
Context Used: For every finding, write a red test with proof and... (source)
|
@desimone can probably chime in here but I think there was two on purpose? One for actually testing the guide and one for content? That said, removing duplicates makes sense to me if the tests can still build with the configs. |
|
@nickytonline if we have separate configuration files for the docs content and the tests, this opens up the possibility for the two to get out of sync. If this were to happen, then the tests would no longer verify that the docs content is correct. In contrast, if there is only one copy of the configuration files, then the tests should accurately verify the correctness of the docs content. But please do let me know if I'm misunderstanding something about the setup here. |
I'm definitely pro one config for each, I just thought there was a reason we needed to have duplicates for the tests, that's all. We're probably good to merge this if all checks pass. |
2 participants
Summary
Many of the Guides pages have example config files in the content/docs/examples/guides folder. Most of these have both .yaml and .yaml.md versions of the config. The plain .yaml files are used in automated tests, while the .yaml.md files are the ones actually included in the site source.
This opens up the possibility that the tested configurations could drift out of sync with the rendered guides.
Instead, let's use the webpack "raw loader" to include the plain .yaml files in the guide pages directly, using explicit components instead of the Markdown backtick fences (```).
Related
n/a
AI disclosure
Refactor performed by Claude Opus 4.5.
Checklist