feat: doc tags (same as blog tags) #3646

isaac-philip · 2020-10-27T18:39:04Z

Note: PR completed by @slorber

Breaking changes

Some theme components are refactored and you may need to upgrade/re-swizzle them
Some classNames have been refactored a bit
Blog tag custom permalinks are prefixed by /blog/tags/<myTag> (let me know if you have an use-case for unprefixing them, we can restore that behavior if really needed)

Motivation

Implement doc tags, similar to existing blog tags

Allow tags frontmatter
Create tag list page, ordered by letter
Create tag doc list page, displaying docs with a given tag
Add inline tag list to the doc page footer (above edit/updatedAt)
The docs tags page do not display any sidebar: this is expected because there is 0-n sidebar we could display for a versioned tag list

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

test + dogfood/peview

- Addition of plugin-content-docs - Addition of DocTagsListPage in `docusaurus-theme-classic` ! Error exists for this commit towards the theme aspect and help required. Commit towards facebook#3434

facebook-github-bot · 2020-10-27T18:39:22Z

Hi @isaac-philip!

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file.

In order for us to review and merge your code, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

docusaurus-bot · 2020-10-27T18:41:20Z

✔️ [V2]

🔨 Explore the source changes: 58367bb

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/611d4abc00054300074b5878

😎 Browse the preview: https://deploy-preview-3646--docusaurus-2.netlify.app

slorber

I've commited various changes to your branch to help you get started.
My code is not production ready nor tested, but it's mostly to help you figure things out and create a nice PR.

I only handled the creation of the tas list page, you can proceed to create one specific page per tag in the same way.

Note each version has a:

set of docs
a tag list
a page per tag linking to the docs having it in the same version

Let me know if you need more help

Also, don't forget to sign the FB CLA.

slorber · 2020-10-28T18:49:58Z

packages/docusaurus-plugin-content-docs/src/index.ts

+          const tagsProp = mapValues(loadedVersion.tags, (tagValue) => ({
+            name: tagValue.name,
+            permalink: tagValue.permalink,
+            count: tagValue.docIds.length,
+          }));
+          const tagsPropPath = await createData(
+            `${docuHash(`tags-list-${loadedVersion.versionName}-prop`)}.json`,
+            JSON.stringify(tagsProp, null, 2),
+          );


this is how you create a component prop as json object (should rather be moved to props.ts and have an explicit type)

packages/docusaurus-plugin-content-docs/src/index.ts

slorber · 2020-10-28T18:51:15Z

packages/docusaurus-plugin-content-docs/src/index.ts

+
+        async function createTagPage(tag: VersionTag) {
+          // TODO
+          console.log(`todo createTagPage for tag=${tag.name}`);


todo: do something similar to create one page per tag

packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx

slorber · 2020-10-28T18:53:25Z

website/docs/introduction.md

@@ -3,6 +3,7 @@ id: introduction
 title: Introduction
 description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
 slug: /
+tags: [test-tag, myOtherTag]


just an example

packages/docusaurus-plugin-content-docs/src/tags.ts

slorber · 2020-10-28T18:54:43Z

packages/docusaurus-plugin-content-docs/src/types.ts

 export type LoadedVersion = VersionMetadata & {
  versionPath: string;
  mainDocId: string;
  docs: DocMetadata[];
+  tags: VersionTags;


the tags are per version, it's not just a global set of tags for all the docs of the site, there is one set of tag per version

packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx

website/docusaurus.config.js

packages/docusaurus-theme-bootstrap/src/theme/DocTagsListPage/index.tsx

slorber · 2020-10-29T16:10:32Z

So finally was able to get a deploy preview to work (after fixing the bootstrap theme).

Note:

As you can see, each version should have its set of tags. "current" version has 2 tags, but alpha 66 do not have any tag. This is because only docs of "current" version have been tagged

isaac-philip · 2020-11-13T06:46:42Z

Hey @slorber , thanks for this.
it is indeed helpful as I just had a glance.
Should help fix things this weekend and have it ready.
will comment 4 more queries if any.

slorber · 2020-11-13T09:21:52Z

great

let me know if you need help to complete it

facebook-github-bot · 2020-11-15T12:10:11Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

- individual doc tag page added to show docs for that specific tag

github-actions · 2021-05-27T21:54:42Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	93
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-3646--docusaurus-2.netlify.app/

isaac-philip · 2021-05-27T21:57:53Z

still WIP but nearing a review,

next steps is to,

get all links
remove an es-lint error when committing
add the same page to bootstrap theme
add the content for the doc-page

isaac-philip · 2021-05-29T20:32:48Z

Done with the two top items,

~~get all links~~
~~remove an es-lint error when committing~~
add the same page to bootstrap theme
add the content for the doc-page

isaac-philip · 2021-06-14T14:52:39Z

Hello @slorber , require some guidance here please.

for now have the page as this

and need to make it like this,

that means the createTagPage within docusaurus-plugin-content-docs would need to save more information than current below, or can we reuse some existing files?

{
  "name": "myothertag",
  "permalink": "/docs/tags/my-other-tag",
  "docIds": [
    "deployment",
    "introduction"
  ],
  "allTagsPath": "/docs/tags"
}

that is more info in the docIds to be used in similar way how the image two renders using this below code,

<div className="margin-vert--xl">
      {items.map(({content: BlogPostContent}) => (
        <BlogPostItem
          key={BlogPostContent.metadata.permalink}
          frontMatter={BlogPostContent.frontMatter}
          metadata={BlogPostContent.metadata}
          truncated>
          <BlogPostContent />
        </BlogPostItem>
      ))}
</div>

Please guide, I checked but the DocContent item props etc I cannot figure out from where to utilize it?

isaac-philip · 2021-06-27T12:59:47Z

@nam-hle can you suggest please?

nam-hle · 2021-06-27T13:35:49Z

Not sure what you need. Please explain more about your situation, perhaps because of my limited knowledge about the codebase.

# Conflicts: # packages/docusaurus-plugin-content-docs/src/docs.ts # packages/docusaurus-plugin-content-docs/src/index.ts # packages/docusaurus-plugin-content-docs/src/types.ts # packages/docusaurus-plugin-content-docs/src/versions.ts # website/docusaurus.config.js

slorber · 2021-08-18T18:01:48Z

Thanks @isaac-philip, I've completed your PR and made some useful cleanups/refactors to avoid code duplication and swizzle theme comps more easily.

Unless someone has any comment I'll merge it tomorrow.

isaac-philip · 2021-08-18T18:22:37Z

thanks @slorber !!

😇

[v2] tags to doc, same as tags to blog - [IN PROGRESS]

5b00807

- Addition of plugin-content-docs - Addition of DocTagsListPage in `docusaurus-theme-classic` ! Error exists for this commit towards the theme aspect and help required. Commit towards facebook#3434

isaac-philip requested review from lex111 and slorber as code owners October 27, 2020 18:39

slorber added 2 commits October 28, 2020 19:48

docs: make tags list page work

f618a72

temp: disable onBrokenLinks

4949fb6

slorber reviewed Oct 28, 2020

View reviewed changes

slorber marked this pull request as draft October 28, 2020 19:28

slorber changed the title ~~[v2] tags to doc, same as tags to blog - [IN PROGRESS]~~ feat(v2): doc tags (same as blog tags) Oct 28, 2020

theme bootstrap: create DocTagsListPage

947b034

slorber reviewed Oct 29, 2020

View reviewed changes

packages/docusaurus-theme-bootstrap/src/theme/DocTagsListPage/index.tsx Show resolved Hide resolved

facebook-github-bot added the CLA Signed Signed Facebook CLA label Nov 15, 2020

sacha-l mentioned this pull request May 17, 2021

Make keyword tags visible and searchable substrate-developer-hub/substrate-how-to-guides#10

Closed

DocTagsPage added and functionality too

bc56aba

- individual doc tag page added to show docs for that specific tag

Added all Docs Tags Link

59212bb

slorber added 4 commits August 17, 2021 16:12

add some shared tag utils

9c7773d

move tag tests to _dogfooding

53337bf

fix type

5d11d6e

slorber mentioned this pull request Aug 18, 2021

[i18n] Making everything translatable (website title, description...) #4542

Open

4 tasks

slorber added 3 commits August 18, 2021 13:31

finish DocTagDocListPage

3c358b4

Extract DocItemFooter + add inline tag list

d6bbbb4

minor fix

7075b98

slorber added the pr: new feature This PR adds a new API or behavior. label Aug 18, 2021

slorber added 4 commits August 18, 2021 16:27

better typings

ea612f3

fix versions.test.ts tests

7bc7473

add tests for doc tags

0a6d771

fix tests

2c21138

slorber added the pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. label Aug 18, 2021

slorber added 8 commits August 18, 2021 18:15

test toTagDocListProp

134b896

move shared theme code to tagUtils

724b27d

Add new theme translation keys

51fd4ab

move common theme code to tagUtils + add tests

1708882

update-code-translations should handle theme-common

c3a1c76

update french translation

50b8c78

revert add translation

b3231ee

fix pluralization problem in theme.docs.tagDocListPageTitle

15f3a44

slorber marked this pull request as ready for review August 18, 2021 17:16

slorber added 3 commits August 18, 2021 19:26

add theme component configuration options

3171b83

add more tags tests

f460912

add documentation for docs tagging

58367bb

slorber changed the title ~~feat(v2): doc tags (same as blog tags)~~ feat: doc tags (same as blog tags) Aug 19, 2021

slorber merged commit f9c79cb into facebook:main Aug 19, 2021

slorber mentioned this pull request Aug 19, 2021

Help us translate the Docusaurus website #3526

Open

This was referenced Aug 19, 2021

refactor: various tags improvements #5386

Merged

[v2] tags to doc same as tags to blog #3434

Closed

swyxio mentioned this pull request Sep 2, 2021

beta.5 docs tags feature - better validation for malformed tags #5478

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: doc tags (same as blog tags) #3646

feat: doc tags (same as blog tags) #3646

isaac-philip commented Oct 27, 2020 •

edited by slorber

Loading

facebook-github-bot commented Oct 27, 2020

docusaurus-bot commented Oct 27, 2020 •

edited by netlify bot

Loading

slorber left a comment

slorber Oct 28, 2020

slorber Oct 28, 2020

slorber Oct 28, 2020

slorber Oct 28, 2020

slorber commented Oct 29, 2020

isaac-philip commented Nov 13, 2020

slorber commented Nov 13, 2020

facebook-github-bot commented Nov 15, 2020

github-actions bot commented May 27, 2021 •

edited

Loading

isaac-philip commented May 27, 2021

isaac-philip commented May 29, 2021

isaac-philip commented Jun 14, 2021

isaac-philip commented Jun 27, 2021

nam-hle commented Jun 27, 2021

slorber commented Aug 18, 2021

isaac-philip commented Aug 18, 2021

feat: doc tags (same as blog tags) #3646

feat: doc tags (same as blog tags) #3646

Conversation

isaac-philip commented Oct 27, 2020 • edited by slorber Loading

Breaking changes

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

facebook-github-bot commented Oct 27, 2020

docusaurus-bot commented Oct 27, 2020 • edited by netlify bot Loading

slorber left a comment

Choose a reason for hiding this comment

slorber Oct 28, 2020

Choose a reason for hiding this comment

slorber Oct 28, 2020

Choose a reason for hiding this comment

slorber Oct 28, 2020

Choose a reason for hiding this comment

slorber Oct 28, 2020

Choose a reason for hiding this comment

slorber commented Oct 29, 2020

isaac-philip commented Nov 13, 2020

slorber commented Nov 13, 2020

facebook-github-bot commented Nov 15, 2020

github-actions bot commented May 27, 2021 • edited Loading

isaac-philip commented May 27, 2021

isaac-philip commented May 29, 2021

isaac-philip commented Jun 14, 2021

isaac-philip commented Jun 27, 2021

nam-hle commented Jun 27, 2021

slorber commented Aug 18, 2021

isaac-philip commented Aug 18, 2021

isaac-philip commented Oct 27, 2020 •

edited by slorber

Loading

docusaurus-bot commented Oct 27, 2020 •

edited by netlify bot

Loading

github-actions bot commented May 27, 2021 •

edited

Loading