mage-os / devdocs-website Goto Github PK

In the menu, it is no visual indicator which elements have children.

You must manually scroll to the very top to access the header for using the theme switcher and search.

It would be great if the header is sticky or at least pops in if you scroll up a bit so that you have quick access to features in the header.

Example: https://docusaurus.io/docs/markdown-features/code-blocks
If you scroll down and afterwards up a little, the header pops back in. Desktop and mobile.

Currently there is no overview about the sections of the page while you're scrolling / reading on a page.

It would be great if there is a sticky overview where you can keep track of the page and where you are at all the time.

Example: https://docusaurus.io/docs/styling-layout

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams

The devdocs repo is a collection of markdown files. There is no place to upload images/screenshots or other media. Obviously, it makes sense to add different media files here and there.

We must implement a directory structure for images in the devdocs repo and render them correctly. Please consider potentially resizing the images for mobile views.

Touching or enter links is very difficult for mobile user (Accessibility)
Should be improved.

Currently, there are no meta tags or schema.org/social tags for the site. Ideally, we don't have to manage those manually. The task for this issue is to come up with a concept of how we can easily manage the necessary meta tags without manually adding them everywhere.

The devdocs are freshly generated, and only a few parts have been reviewed by real humans. It might make sense to tell the user about this and also encourage them to review the pages themselves.

Would be nice to have a /swagger or /api endpoint to see all available APIs.

Since merging #16, it looks like the devdocs are broken - or at least the deployment: https://github.com/mage-os/devdocs-website/actions

Currently devdocs are down:

@DavidLambauer, could you have a look?

Awesome work on the devdocs guys! I got two small feedback points.

Darkmode

When reading code blocks, the dark mode hides the text.

We want an additional CLI command that reads the documentation content and creates FAQs based on it. The FAQs should be added to the end of the site. The CLI command should read the content, pass it to GPT, and generate the FAQs.

Make sure to add structured data so we can make use of Google faq rich snippets
https://developers.google.com/search/docs/appearance/structured-data/faqpage?hl=en

The navigation on the left side should be sticky while scrolling so that you have access to it all the time.

Example: https://docusaurus.io/docs/styling-layout (just scroll down if the page is wide enough to show the left side navigation)

Currently you lose focus quickly if you scroll down on pages like https://devdocs.mage-os.org/docs/main/overview-of-magento-2-development#models

Currently you must scroll all the way to the top manually to reach the navigation (fixed by #42) or the search bar.

A little "scroll to top" button would enhance usability.

Example: https://docusaurus.io/docs/styling-layout (scroll down and a little bit up to show the icon on the bottom right)

Currently, the contributor in the markdown files has to make sure the ToC is added manually. Also, the jump marks need to be done manually. We could generate it I suppose.

To make contributions as easy as possible, I want to have a Edit this site on GitHub Link on every page.

Still trying to figure out what the cause is, but right now, almost every deployment triggers a 503. This can be resolved by an artisan optimize:clear or similar cache-dropping methods.

Right now, we have a hotfix in place where a cron checks the site for a 503, and if so, fires the command.

This ticket is for documentation purposes...

For whatever reason the search is broken for me currently: