Add funnels and design improvement

[zapaul]

As noted here, I extended my previous PR https://github.com/zaphosting/docs/pull/1248 to create this bigger PR.

What it roughly does (if I didn't forget something):

• Let's us link guides to specific products that are used in them.
• Displays used products with a link to them at the top of the guide.
• Loads a docs coupon from the main application and displays it in the sidebar.
• Adds a custom element to be integrated into the docs content to advertise the voucher additionally (or at all for mobile devices since the sidebar coupon is only for desktop devices).
• Improves the custom YouTube element. In it's current version, the video shrinks in the flexbox. If there is not enough space at certain viewport sizes, the video is a very thin line, horizontally speaking. The video part now has a fixed width with shrinking disabled and the content takes up the rest of the element automatically (flex: 1 1 0%). I also made the drop shadow a little more visually appealing (in my mind) and make it the same as my new elements. I've also slightly increased the line-height of the text.
• As discussed before, shrinks the sidebar to 300px while reducing the font size.
• Removes a bigger breakpoint for the content container. This practically makes the main content and the sidebar on the right less wide. As a result, the text doesn't spread across 75% of the screen, which makes it more exhausting to read on bigger screens since you have to correctly move your eyes from one side of the screen to the other side while staying in the correct line you were reading. This is also why newspapers have columns. I think this is pretty simple yet effective for improving the experience.
• Adds a little more space between the content and the sidebar on the right.
• Adds a bit more space between categories in the sidebar on the left. In it's current state, it is hard to scan the sidebar to find different categories. With just a bit more space above/below the different categories, it is much easier to differentiate between them at first glance.
• Replaces a few icons with more modern looking ones (for instance the dropdown icon in the navigation, which is currently a literal triangle).
• Removes justification from the content text. It just adds quite a bit of spacing in some lines (which looks weird) to justify the text while I personally don't see any benefit in the text being a block. I think this is quite unusual.

Noteworthy explanations for usage:

Linking products to guides

This works by using meta data (or how Docusaurus appears to be calling it: front matter) to the specific doc files in a services key. The services can be configured in src/utilities/services.map.tsx. The key must match the entry in the services key of the doc file. I added premium storage and cloud gameserver to the gameserver backups doc as an example. They have a translatable title and url for displaying them with a link in the docs. The URL supports interpolation so the current language and a variable from the main config (marketingSite, which should hold the URL of our site advertising and describing the products, so just zap-hosting.com aswell for now - helps us to change the URL easily in case needed) can be used in the URLs. With this, some URLs practically do not need to be translated because for example '{marketingSite}/{language}/shop/product/premium-storage/'will work for both languages. It still allows us to set any link for a specific product or language though.

Voucher loading architecture

Since the voucher is loaded in multiple elements on the site and I wanted it to be only loaded one single time (and not being loaded another time when switching between doc pages), I used a React context at the root level of the site, which is what Docusaurus recommends: https://docusaurus.io/docs/swizzling#wrapper-your-site-with-root

As I mentioned in the previous PR, I'm still not a React dev by any means though.

Voucher element in the content

Just like the YouTube element for example, this can be added in the content (after a few headings would be the best place I'd think). I also added this as an example in the gameserver backups docs. By default, it also displays the products from the doc page and labels them with something like "ready with all the products used in the guide:" followed by the products. Since not all products can be used with our vouchers (external products like FiveM upvotes), you can add the showProducts flag and set it to false:

<InlineVoucher showProducts={false} />

It will then display alternate content naming a few reasons why the user should give ZAP-Hosting a try. It does the same if no product is linked to the current doc page. You can find out what products can be used with the voucher in the backend, the code is currently docs-50. It should have the usual configuration for these types of vouchers, just like the exit intent vouchers for example.

[ThatGuyJacobee]

Looks great! Thanks for providing the extra info about configs and usages. :)

I've played around with it and can't find any bugs at the moment (minus the voucher stuff as endpoint can't be reached atm) which is awesome. The one thing that I believe would look better is moving the "Linked Products" section below the guide's title, but that's just my own opinion.

Otherwise, the changes look great and make sense, nice work! We will definitely start introducing the product link and voucher stuff across our existing guides soon, alongside future ones of course. 🙂

[zapaul]

Thanks for the feedback :)

minus the voucher stuff as endpoint can't be reached atm

I just sent you a PM (I think) so we can make it work in your local environment in order for you to take a final look :) The production endpoint does work, but the request is not allowed due to the origin (your local environment) not being whitelisted for cross-origin requests.

[fgalz]

This definitely looks very good overall. I would also agree with @ThatGuyJacobee here. The position with the products used looks a bit out of place and would have a more uniform structure if this was done directly under the title, which is where the customer starts with the document. Is that something that can be adapted or is it not feasible?

[zapaul]

Thank you for your feedback too, @fgalz.

Is that something that can be adapted or is it not feasible?

I could "swizzle" https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx, while I would consider the component to be rather unsafe to swizzle because it has logic in it. It certainly is possible, but we would have to keep track of changes in the logic from the original theme. It isn't too much code though and the latest changes were pushed two years ago. However, you will have to keep in mind that this will only work if the title is used from the doc's front matter/meta information at the top of the doc file. If you disable that or add an h1 into the content of the doc, it will be used from the doc content itself. In this case, it will be above the main headline again.

What do you think? For consistency, it might be good to keep it above the heading in every case.

[fgalz]

We generally do not use h1 tags in the Docs documents. For the title, we use the information from the metadata. Docusaurus sets this automatically, so no additional h1 is required there.

[zapaul]

If you've always used the metadata for the title in the past and will continue to do so, my new commit will do as requested @fgalz.

[fgalz]

Glad to hear that! What is the current status of the implementation at backend level? Is it already fully functional and ready for us to merge?

[zapaul]

Everything is ready to go :) @fgalz

[fgalz]

Alright, I'll merge this tomorrow and add the products to all relevant guide documents. :)

[Blumlaut]

@zapaul is it intentional that the inlineVoucher takes up about 50% of the doc container vertically with nothing but blank space on 1080p monitors?

Changing the height to 3 or 4rem each already makes it much nicer to look at in my opinion:

[zapaul]

Thanks @fgalz.

I wanted the element to have more space around it than the individual parts of the content have between one another to make sure the element is recognized as a somewhat unrelated insertion, like a short commercial break if you will. Something like 4.5rem works great for me too, though. You can merge https://github.com/zaphosting/docs/pull/1271 then if you would like to :) @Blumlaut