Dvc.org: docs: add metadata markup capability to docs template so docs can have unique SEO descriptions and metadata

[jeremydesroches]

Requirements

• [ ] default meta description for /doc items is blank (no description)
• [ ] when front matter tags are added to /doc items then meta tags are added, following /blog pattern
• [ ] front matter tags are optional, e.g., only description, only title, title + description, none. Unused tags don't need to be added to front matter.

What?
All docs pages currently use the same meta description and it's not possible to customize it for each doc. In the existing blog template, unique metadata is added by using markup at the top of each markdown file as follows:

title: August '20 Community Gems
description: | A roundup of technical Q&A's from the DVC community...

I propose adding the same capability to the docs template so that docs can have unique metadata (if added to the front matter).

Why?
SEO analyzers/site audits flag this as an issue because a unique (and well written) description often improves clickthrough rates on search results, which leads to better rankings.

There are currently ~90 /doc pages on the dvc.org domain with duplicate descriptions. Adding unique descriptions to all/most of the docs could have a material positive impact on overall rankings in the medium to long term.

Adding this feature would allow for a partial fix for two open general SEO issues: it's a best practice to have unique descriptions (#1118), which could then be updated on all docs and

• [ ] the meta description tags considered "reviewed" (#1119).

If the docs template was updated to use custom metadata like blog posts, then

• [ ] #857 re: content previews should also be addressed.

The content preview (e.g., og:description) is not unique for the same reason: different tags but generated from the same text. 😉

This should function as described in #982 ("easily replace default og-tags in header with the ones needed for current page"), but if no custom tags are added to a given doc, the default tags should remain.

How?
I investigated how this is working for blog posts and tried adding similar metadata to a doc on my local... just in case the renderer picked it up (it didn't 🙃). So it appears the docs template and page generation need to be updated.

To fix the duplicates issue, only the meta description would be required. There is no need or benefit to customizing the meta title for most of the docs as the title is simple and should only reference the command or feature. However, for tutorials, use cases, or other long-form docs it would be good to have the option to edit the meta title for SEO purposes.

[jeremydesroches]

Hey @jorgeorpinel, I think this would be a good complement to the GSoD work. With this I could update some/all of the docs descriptions as I make other updates.

I can probably figure out how to do this, but it would be great if someone who was more familiar with the site generator (or did the blog meta work) could help out. Let me know what you and the team think!

[jorgeorpinel]

Agree. @shcheklein @rogermparent should we prioritize this for coming weeks? Thoughts on how to implement?

BTW this is sort of a duplicate of #982, can we merge them please @jeremydesroches? This one has more info so let's keep this one, just bring in any info that's not included (if any) from that older one into the description above.

Some follow-ups:

Can you try to summarize the requirements as bullets or check boxes in the description of this issue Jeremy? E.g. which fields to support, etc. (or is it the exact same stuff as in the blog?)

then #857 re: content previews should also be addressed

OK, I closed that issue and added a check box to the description above instead.

To fix the duplicates issue

Which one are you referring to there? Didn't get that part (feel free to clarify in the description/requirements).

Thanks

[rogermparent]

Adding this would be quite easy, I think. We just need to decide which fields we want to add, what SEO tags they translate to, then map these two pieces of info to the docs page queries and react-helmet components in the template respectively.

Assumedly from the OP, this would just be a description field mapping to the description meta tag, and whichever others that may need to be duplicated to.

[shcheklein]

Can we auto generate all needed meta fields (description, images, etc, etc). It would be great to avoid us having to update and maintain new fields for every single page in docs.

[jeremydesroches]

BTW this is sort of a duplicate of #982, can we merge them please @jeremydesroches?

982 is very similar and I added the detail about defaults vs. custom tags. Ideally docs could continue to use the default tags until we update and add the front matter with custom tags. That's how it works for blog posts (I tested it out). If you leave a custom tag blank, it's replaced with a default "blog" tag.

Can you try to summarize the requirements as bullets or check boxes in the description of this issue Jeremy? E.g. which fields to support, etc. (or is it the exact same stuff as in the blog?)

The minimum to fix the "duplicate meta descriptions" issue is only the description. The title might be useful for tutorials and use cases. So it's a subset of what blog posts use. I was thinking that if the fallback to defaults works as with blog posts, then it would be simpler to follow the blog implementation.

[jorgeorpinel]

@jeremydesroches by "duplicate meta descriptions" you mean that every doc page has the same meta description right? Just checking

Can you try to summarize the requirements as bullets or check boxes

only the description. The title might be useful... if the fallback to defaults works as with blog posts

So again, can you clearly summarize the desired requirements please? TBH I didn't fully understand the answer. Thanks

[jeremydesroches]

So again, can you clearly summarize the desired requirements please? TBH I didn't fully understand the answer. Thanks

OK @jorgeorpinel. Added to original description. Let me know if anything can be added or clarified.