Skip to content

Fix Client Briefings Template Link

This PR fixes the link to the client briefing template.

JIRA tickets: https://tasks.opencraft.com/browse/BIZ-1667

Merge deadline: "None" if there's no rush, "ASAP" if it's critical, or provide a specific date if there is one.

Author Notes:

This is a one line fix that is, as best I can determine, the most economical and least disruptive one, but it took some work to decide on that. Here's why:

Linking to '../client_briefings_template/` is linking to the rendered URL for ReadTheDocs but doesn't link to the actual markdown file, which means if you're just browsing the docs on GitLab or through a markdown renderer, this link will fail. It does work with mkdocs when using the live server feature.

We could do a link to the public URL of the page on ReadTheDocs, but that means you'll no longer get the local copy-- imagine if you're clicking through your local mkdocs server and choose the client briefing. You edit the briefing in your editor and expect it to update, but it doesn't-- because you're looking at the live version and unless you paid attention to the URL, you haven't figured that out yet. You then begin trying to diagnose why the render system is broken until you realize what happened.

The 'real' solution would be to put the page in the navigation proper. However, there are some problems with this:

You CAN nest sections in mkdocs, but they don't render as you might expect. It's weird-- a top level section just acts as a heading in the nav and doesn't distinguish itself properly.

Adding another section under that does distinguish itself... but it autoexpands, making the nav busier that we'd want it to be when just starting out.

So if we wanted to REALLY fix this, we'd probably need custom templating. If not, we could try having ReadTheDocs build it anyway to see if it handles the nav more sanely than our local mkdocs renders.

Reviewers

  • OpenCraft reviewer TBD
Edited by Fox Danger Piacenti

Merge request reports

Loading