docs(docsWeb): redesign docs, add nested navigation link list

[donmckenna]

Total redesign of documentation styles, page structure and hierarchies.
Navigation accommodates nested links and offers parameters for link positioning and styles.

ISSUES CLOSED: #630

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/scullyio/scully/blob/main/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Other... Please describe:

What is the current behavior?

Current docs become increasingly difficult to navigate the more pages are added.
Some styles and functionality make content difficult to find and read.

Issue Number: #630

What is the new behavior?

This PR makes it easier to organize and navigate nested, related pages of documentation.
This is augmented by a style overhaul, laid out in issue #630 and https://github.com/donmckenna/scully-docs-navlist-redesign

Does this PR introduce a breaking change?

• Yes
• No

Only the docs are incompatible with previous versions of the docs.

Other information

• I've kept the original file structure as close to the original as possible. Some pieces have changed, but I tried to build it as simple and modular as possible for future contributors.
• An additional change not laid out in my original issue is new Showcase styles. Currently logo images are being used/linked. This makes for unpredictable image sizes. I changed it to small, equal sized screenshots of each page. This affects PR fix(docsWeb): fix missing showcase logos #751 / makes it obsolete. This design choice may or may not be what you're all looking for. Open to suggestions.
• When building the syntax highlighting styles, I followed the current docs suggestion of using PrismJS. When applying these styles to the actual docs site I saw it used HighlightJS instead. I was able to get the md plugin using Prism instead of Highlight, but this was a change in /lib/ not /scully-docs/ so I'm not sure if this is the best way to go about it.
• There are pieces I'd like to complete, which are not included in this PR such as:
  • Fully responsive styles. I have the basis for this, but I wanted to submit this PR sooner than later, and the current docs aren't that responsive either, so this will be "Phase 2".
  • Animated navigation open/closing. It is simply easier to not animate them at this time, but it would be a nice UI element to have later.
  • There are some custom CSS elements you can use to easily style .md elements. I will be making additional documentation to describe how to use these, and possibly expand on more style guides for contributing to the docs.
  • Some pages were broken up into different pages to separate their parts into smaller pieces. On a few of these original pages the Schematics list was referenced. As the lists/links alongside the Schematics list on these pages were broken up into their own pages / single sources of truth, so were the Schematics list items. However there were only Schematics list headings and no content to go along with them. So to keep these alongside the other elements in the navigation hierarchy, each Schematic heading has its own page, but no content. This was a very long way of describing why the Schematics have no content.
  • Unless I'm missing something, the Spanish docs select dropdown on the current docs doesn't work, despite lang: es pages existing in the docs. Some es pages were versions of en pages which are now split into separate pages. My Spanish is not great so I unfortunately couldn't break them up myself. So because the current docs have minimal Spanish content, and to keep things simple, I've poised the navlist to accept and filter es pages, but currently it just ignores them.
    • I think it can be implemented where, when a user is on an en page, and then selects es, the page can bring them to the es version of that same page, but if an equivalent es page isn't available, it could just redirect to the es version of "Getting Started" or something. I've conceptualized this and build a little place for it to go, but to keep things simple and since the current docs don't seem to use this correctly, this isn't included with this PR.

[donmckenna]

Looks like Jest snapshots are failing, which would make sense.
However I don't have much experience with these. Tried doing a npm run jest:test -- -u locally but I'm not sure it did what I want.
Any guidance would be appreciated.

[msacket]

I had a similar issue until I realized I had to pull changes from upstream main into my fix-branch, then run the npm run jest:test -- -u. I'm not sure if that's the issue here, but tests were working locally until I did that. With help from @SanderElias, The steps I used were something like:

# pull any upstream changes into my local fix branch
git pull upstream fix-branch

# fix and update snapshots
npm run test
npm run jest:test -- -u

#push changes back to the fix branch on github
git push origin fix-branch

BTW - Demo of the docs looks slick.

[donmckenna]

Added the ability to render different navList layouts depending on a page's lang, and switch between available languages.
Tried to build it for the end result of making it as simple as possible to add new languages: 1. Name file, 2. Define lang, 3. Place file in any directory alongside its other language counterparts. NavList and LangSelect (and Scully) handle the rest.

Language select dropdown contains links, auto-generated from every available language.
Its indicators show the current page's language, and/or if a given page has no additional language translation equivalent page.

If a given page has an equivalent in another language (indicated by a _es type suffix on the .md filename), the dropdown link will link to this translated page.
If a given page has no other language equivalents, the dropdown will indicate that there are pages with this language available, but not this particular page, and will link to a default "intro" or "no translation available" page for that language.

The languages are filtered before constructing the navList, so the way it builds itself is unaffected by multiple languages. So there should be no blank directories in the navList for incomplete languages, for example.

Also added some extra abilities to customize parent directory linkText.

Also added an "introduction" page placeholder Spanish page. My Spanish is not great, so it's all Google translated, but it gives an idea of how the pages function.

There is also a small js script for "clicking outside" the lang-select to close it. I preferred this over clicking the button itself to toggle it. Hopefully it's not too intrusive. I did not want to include js, but it does help the ux in this particular case imo. I chose this over a simple select element so we could embed additional information (like whether or not a page has a translated equivalent), and have more control over the ui for language selections than a simple select/option allows.

[SanderElias]

LGTM

@aaronfrost can you give this a review?

[Villanuevand]

Looks freaking awesome for me...
@donmckenna thanks for this great work....

[GuzmanPI]

Looks great!

[jorgeucano]

I will merge this PR the weekend, I need to change some text, but really thanks for your work and all the patience you have