mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-07-09 03:49:52 +02:00
e3a1ee2e5b
This pull request adds a custom `docmd` plugin to improve how documentation links to source files are handled, ensuring that repo-root-relative links work both when editing locally and on the published site. The main changes include introducing the new plugin, updating configuration to use it, and documenting its behavior. **Plugin integration and configuration:** * Added a new local plugin `github-source-links` in `docmd-plugins/`, which rewrites repo-root-relative links (e.g., `/src/.../Foo.cpp`) in Markdown files to absolute GitHub blob URLs during the documentation build process, ensuring links remain functional on the published site. [[1]](diffhunk://#diff-c2c746e6974a6cfdd229031c2977f2bb0dca37c6d5f598ed45dc0d9f0b74c7caR1-R52) [[2]](diffhunk://#diff-a97f3ce59c97313aacd716b9874b445d162c45ee2e6ef9fd2db59fe17235e1cfR1-R8) * Updated `docmd.config.json` to register the new plugin under the `plugins` key, enabling it for documentation builds. * Updated `package.json` to include the plugin as a dependency, referencing the local plugin directory. **Documentation updates:** * Updated `README.md` to document the new `docmd-plugins/` folder, explain the purpose of repo-root-relative links, and describe how the plugin rewrites these links for the published site.
53 lines
2.0 KiB
JavaScript
53 lines
2.0 KiB
JavaScript
// docmd plugin: github-source-links
|
|
//
|
|
// The dev docs link to source files with repo-root-relative paths such as
|
|
// "/src/modules/.../Foo.cpp". VS Code resolves those against the workspace root,
|
|
// so they stay clickable while editing locally. On the published static site,
|
|
// however, a "/src/..." link resolves against the site origin and 404s.
|
|
//
|
|
// This plugin rewrites those links to absolute GitHub blob URLs so they work on
|
|
// the published site, while the Markdown sources stay untouched (keeping local
|
|
// VS Code navigation intact).
|
|
//
|
|
// It hooks markdownSetup at the Markdown token level, so it only rewrites links
|
|
// written in the docs' content. docmd's own generated links (sidebar, breadcrumbs,
|
|
// canonical tags) are never seen here, which matters because an internal doc route
|
|
// like "/tools/build-tools" is otherwise indistinguishable from a repo path like
|
|
// "/tools/BugReportTool" once rendered to HTML.
|
|
//
|
|
// docmd appends a trailing slash to the rewritten links (".../Foo.cpp/"); GitHub
|
|
// resolves that to the file anyway, so it is left as-is for simplicity.
|
|
|
|
const REPO_BLOB_BASE = 'https://github.com/microsoft/PowerToys/blob/main';
|
|
|
|
export default {
|
|
plugin: {
|
|
name: 'github-source-links',
|
|
version: '1.0.0',
|
|
capabilities: ['markdown'],
|
|
},
|
|
|
|
markdownSetup(md) {
|
|
const defaultRender =
|
|
md.renderer.rules.link_open ||
|
|
((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options));
|
|
|
|
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
|
|
const token = tokens[idx];
|
|
const hrefIndex = token.attrIndex('href');
|
|
|
|
if (hrefIndex >= 0) {
|
|
const href = token.attrs[hrefIndex][1];
|
|
|
|
// Only repo-root-relative links ("/src/..."). Leave protocol-relative
|
|
// ("//host"), absolute ("https://..."), relative and anchor links alone.
|
|
if (href.length > 1 && href[0] === '/' && href[1] !== '/') {
|
|
token.attrs[hrefIndex][1] = REPO_BLOB_BASE + href;
|
|
}
|
|
}
|
|
|
|
return defaultRender(tokens, idx, options, env, self);
|
|
};
|
|
},
|
|
};
|