Document engine features

[casperdcl]

Are all features added to https://dvc.org/doc/user-guide/contributing/docs?

Missing things:

• Glossary tooltips <abbr>
• Admonitions <admon> or <admonition> - usage and note Minor fixes #3422 (comment)
• <cards> with <card> ? (only used in https://dvc.org/doc I think)
• Expandable sections <details>
• Tab toggles <toggle> + <tab> - usage

Really should document docs features as we implement them, even if it's just one line (or at least open follow-up issues to track).

/CC @iterative/docs @iterative/websites

[jorgeorpinel]

Thanks for the summary. Documenting admonitions was a task in #3382 and for toggle/tabs in #2939 but indeed there are some other features we've always had and never documented so let's keep this one instead!

I'm just not sure whether to put it in the contrib guide or maybe in the README (and link there from the guide). Especially if we're extracting the docs engine into it's own repo cc @julieg18 WDYT

[casperdcl]

I'd say p1: contrib guide (that's where everything else is currently consolidated), p2: upgrade readme

[yathomasi]

I'm just not sure whether to put it in the contrib guide or maybe in the README (and link there from the guide). Especially if we're extracting the docs engine into it's own repo

Personally, I would also say contrib guide.
It does make sense to have it on project README but we don't have a proper README and also the repo is private as of now.

[jorgeorpinel]

What about contrib guides of other product doc sites that also use this engine e.g. cml.dev/doc of mlem.ai/doc, should they all have the same repeated info. about the doc engine features? I think it makes more sense to document them in iterative/gatsby-theme-iterative#17 and link from each contrib guide.

[casperdcl]

@yathomasi when is https://github.com/iterative/gatsby-theme-iterative going to be made public? If it's soon then we should:

• transfer this issue there
• close document features gatsby-theme-iterative#17 as a duplicate
• consolidate everything into its README
• delete most of dvc.org/doc/contributing, inserting a link to the readme above instead.

Otherwise definitely should continue to consolidate everything in dvc.org/doc/contributing.

[yathomasi]

@yathomasi when is iterative/gatsby-theme-iterative going to be made public?

I think we can move ahead, and update the README(at least have some basic details) and make the repo public.

Here is a roadmap for our docs-engine theme. Now, we are about to step into phase-3. For the package to be easily usable for everyone, we need to generalize and optimize it more, which will take some time.

• transfer this issue there

I think we can close this in favor of iterative/gatsby-theme-iterative#17

• delete most of dvc.org/doc/contributing, inserting a link to the readme above instead.

Specailly doc-style-guidelines-javascript-and-markdown portion

[casperdcl]

ok moving to iterative/gatsby-theme-iterative#17