Spike technical approach for hosting v4 in a subfolder

romaricpascal commented 1 year ago

What

Explore the impacts of hosting v4 in a subfolder, especially:

links (eg. moving to relative links, it might be worth thinking at some linting there as well)
making the frontend-docs menu work with two sets of documentation (we may want to look into what publishing docs are doing)
having a way to navigate between v4 and v5 docs (similarly, looking at publishing docs may be a good start, but we may want to anticipate how to look at more than 2 versions for future upates when we expand our public API, for ex).

Why

We need to validate the feasibility of our plan for hosting older version of frontend-docs in sub folders

Who needs to know about this

Developers

Done when

[ ] We've listed the constraints hosting v4 in a subfolder raises
[ ] We have a plan to work with each of these constraints

36degrees commented 1 year ago

I've had a go at spiking this to see what the problems are. It all feels a little bit hacky, but I've managed to get 90% of the way there pretty quickly:

The main 'unsolved' problems are:

When building the table of contents for the v4 section, v4/index.html is seen as a parent of all the other files, which means the nav is generated very differently for the 2 sections
The v4 docs are also included at the very bottom of the v5 sidebar
The v5.x link in the header isn’t highlighted when on subpages for v5

I've found it useful to see how GOV.UK Publishing Developer Docs have done things (the most complex use of the tech-docs-gem I'm aware of). For example, they have a separate 'multipage layout' that got me 90% of the way there for rendering the v4 sidebar.

I think if we needed to we could consider just hard-coding the v4 nav and ignoring the missing highlight of 'v5.x' to get this out the door, but worth trying to tidy a few bits up.

The tech docs gem doesn't really have an owner but it'd be worth thinking about what it'd take to get this supported in a less hacky way.

I'm not sure if I'll get a chance to come back to this before I go on leave, so if anyone else wants to pick this up then please do.

romaricpascal commented 1 year ago

Open a clean PR based on the spike branch, we can iterate the search if necessary if feedback comes in.

romaricpascal commented 12 months ago

Implemented in https://github.com/alphagov/govuk-frontend-docs/pull/384 🥳

alphagov / govuk-frontend-docs