search

vegetable-specification-society / website

0 stars 0 forks source link

Port documentation content from Hugo #11

Open davidjgoss opened 5 months ago

davidjgoss commented 5 months ago

We have started working with Docusaurus for our new website. To have a single location for content and ensure a smooth transition when we put this site live on the cucumber.io domain, it makes sense to bring the docs (from https://github.com/cucumber/docs) in here too.

There have been many ideas and opinions in the past couple of years about what we could/should do with the docs, but we don't want to solve too many problems at once. So, the strategy here will be to port the existing content as-is, resolving to the same paths, with light-touch review as we go to hopefully catch any stale or inaccurate content.

It would be nice to bring the commit history over with the docs content, but it's not a dealbreaker if we can't.

I already ported the Gherkin Reference page as an example here https://cucumber-site-new.netlify.app/docs/gherkin/reference/ - this just took a few minutes of tweaking the Markdown. I'll do a couple more to prove this is workable, including at least one with language tabs.

As discussed today with @mattwynne @mpkorstanje; cc @mlvandijk @luke-hill @brasmusson

mpkorstanje commented 5 months ago

@davidjgoss the most complicated part of the documentation is the multi-language aspect. How do you propose we do this?

davidjgoss commented 5 months ago

@mpkorstanje yeah I wanted to tackle this pretty early. I have a POC started in #14 - much to do but promising so far.

You can see a preview of the first section of the step definitions page here https://deploy-preview-14--cucumber-site-new.netlify.app/docs/cucumber/step-definitions/

davidjgoss commented 5 months ago

How do you propose we do this?

A bit more specifically, I think the language tabs at the top of the page in the current docs are easy to miss. I'd like to see how we get on with having tabs in each part of the page where there is a code sample. Docusaurus will sync the preference across all sections.

We also often see content like this...

image

...which really isn't ideal, and I think we could refactor the way those pages are structured.