Doc squad collab: Create filter-by-tag logic for Zowe Docs Site

[1000TurquoisePogs]

cross-repo links to zowe/docs-site#1767

Problem: Our documentation contains sections a user never needs to read, because it includes instructions for all possible environments but some are mutually exclusive, so a user only needs to read instructions that are relevant to their environnment and what components they want to use.

Proposal: If the user could select from a list what type of environment they have, what components they want to use, what optional features they are interested in, and what they want to do today (install, configure, troubleshoot etc) then the documentation can be filtered to their specific needs, reducing the documentation they see to only what is relevant to them.

Subtasks:

Research doing conditional div hiding by a property (tag) set within a markdown file of the doc
Create react component which guides the user to select tags that the site would use to filter the doc
Determine what filtered docs should look like: missing, or just greyed out?
Create place on site that shows what currently selected filters are, and allow them to be toggled off
By topic, tag each paragraph, table, code example with tags such as ESMs, prerequisites, Zowe component, optional feature, and type of task
Dependencies: Collaborate with the Doc squad to better understand how the doc website software works, and collaborate with them to tag each documentation section according to filter topics.

[skurnevich]

Hi @idontknowjs, @nannanli i see your activity in this issue so i think you may be interested in that, if someone else should be included please share.

Summary of findings so far:

As described in #1767 we can use the Frontmatter of the markdown files, i tried to use this structure for POC, but it could be discussed.

---
meta:
  - tags: {
      architecture: ["Zowe architecture with high availability enablement on Sysplex", "Zowe architecture when using Docker image"],
      desktop: ["App Server"],
      zss: ["Cross memory server", "ZSS"],
    }
---

In this approach tag just pointing to the array of related headers, that is the weak part of idea, it is safer to use header id, but now IDs aren't mentioned in .md file, but generated automatically.
There are several possible options:

• Set custom IDs to headers we use for tags, like {#my-custom-id} - cons - it takes more work to put it manually to all the headers, possible typos.
• Add ids to all the headers automatically using -- "write-heading-ids": "docusaurus write-heading-ids", - quicker but will change all the .md files, so affect the git history.
• Find the actual algorithm used for generating IDs from previous point and use it to convert headers to IDs in our tweaked components.

Then we need to manipulate document content in accordance with tags, i found that we use MDXProvider in tweaked DocItem, and this component allows to add wrapper to manipulate its children, so we can use it like that:

<MDXProvider components={{...MDXComponents, 
                wrapper: props => <TagsWrapper props={props}/>
}}>

And do the children sorting in TagsWrapper.
Issue is that all of contents are similar React children - so header is one of children and paragraph below it - is the separate child, so we add some logic here to calculate that paragraph or any other lower item belongs to some header.
And now we can filter page content and table of contents.

Then we need a tags selector component, i put it to the side panel (tweaked DocSidebar component) and utilized browser session storage to store its state to keep the selection after document change or page refresh.

So i got this as result:

That seems to be enough for POC. Here is a draft PR for that, to see more details in code.
Only issue i have not covered - filtering of the side panel itself, as it is generated automatically and it needs more research if it is possible to connect it with markdown file tags. I found this in the Docusaurus docs, but not sure if we can use it somehow.

Thanks,
Sergei

[skurnevich]

Some updates to follow up Monday's call

• In each case when we manipulated children - we can add a label to let user know that we filtered out some results, something like:
  

• For pointing to some paragraph without a header - we can use 'hidden header' like ###### {#hidden-header} such header will have the ID but would not be displayed on the page as it has no text. In fact, there will be some visible empty space because of the header margin, but we will filter out those empty headers completely as we use it just as a marker.
  I have slightly corrected the POC draft PR code, so next markdown file should work just fine:

---
meta:
  - tags: {
      tag1: ["hidden-header"],
      tag2: ["hidden-header2"],
    }
---

# Page header

First paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Other paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

###### {#hidden-header}

Paragraph that is related to the first tag.

###### {#hidden-header2}

Another paragraph that is related to the second tag.

###### {#hidden-header3}

Third paragraph not related to any tag

It will look just like a regular paragraphs without filters applied:

Part with {#hidden-header3} is needed only to separate unrelated paragraphs, it will be redundant if we have any other header following the tagged paragraph.

[1000TurquoisePogs]

Seems to be complete on our end at this time, so let's close this while we wait for further action.