Skip to content

Add Redirect Feature or Error Documentation Links #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 3, 2025

Conversation

AristurtleDev
Copy link
Contributor

Summary

This PR implements a redirect system for MonoGame error documentation links. The system allows us to create stable, short URLs that can be updated without breaking external references, similar to URL shorteners.

How it works:

  • Create a redirect page in the /errors/ directory such as /errors/setupwine/index.md
  • The page generates a clean URL: https://docs.monogame.net/errors/setupwine
  • When accessed, it automatically redirects to the target documentation.
  • If the target changes only the redirect value needs to be updated.

Example Usage

---
redirect: ./path/to/target/index.md
---

[redirect](./path/to/target.md]

Note

Due to DocFX's document processing limitations, the redirect URL must appear both in the front matter and as a link in the document body. By including it in the body, this ensures that link validation occurs, while maintaining the redirect functionality.

Notes

DocFX Processing Constraints: DocFX cannot validate YAML frontmatter values using its standard link validation. To work around this, we include the redirect URL twice:

  1. In the redirect frontmatter for the redirect functionality.
  2. As a markdown link in the document body for DocFX validation.

Changes Made

  • docfx.json: Added /errors/**/*.md to content build process
  • master.tmpl: Change from redirect_url to redirect property
    • Reason: redirect_url is a DocFX reserved property that bypasses normal processing and skips conceptual.extensions.js, which we need for proper .md to .html link transformations
  • conceptual.extensions.js: Added transformation logic for model.redirect
    • Converts .md extensions to .html in the redirect URLs
    • enables use of standard DocFX relative links in both frontmatter and document body
    • Maintains link validation compatibility

`redirect_url` bypasses the conceptual processing since it runs an internal built in process within docfx to generate the redirect page.
@SimonDarksideJ SimonDarksideJ merged commit 2dc81cd into MonoGame:main Jun 3, 2025
2 checks passed
@dellis1972
Copy link
Contributor

@AristurtleDev

Can we use the errors folder for actual error pages as well (not just redirections? )

e.g I would like to have docs.monogame.net/error/mgfx0001 which is an actual coded error message we have in the code. The page mgfx0001.md would have info on the error, what it is and how to work around it and links to other docs.

@SimonDarksideJ
Copy link
Collaborator

Yes @dellis1972 , that folder is a docs area just like any other I believe. So any document with frontmatter should work.

We can simply try it out if you wish

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants