Toggle lang button

[casperdcl]

Rather than writing separate pages for GH, GL and BB, it would in many cases be easier to write one page with a button to toggle between providers (similar to https://github.com/iterative/cml-website/blob/master/content/index.mdx but far simpler).

See e.g. https://zguide.zeromq.org/docs/chapter1/ for an example of clicking on a language next to code snippets to change the language of all snippets on the page (ofc we can do a lot better design-wise).

md interface options

html tags

# Installation

lorem ipsum...

<toggle>

<GitHub>

*bla bla* standard markdown...

```yml
- uses: iterative/setup-cml@v1
```

</GitHub>

<GitLab>

...

</GitLab>

<Bitbucket>

...

</Bitbucket>

</toggle>

tabbed

https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/

=== "GitHub"

    *bla bla* standard markdown...

    ```yml
    - uses: iterative/setup-cml@v1
    ```

=== "GitLab"

    ...

other ideas?

URL interface options

• cml.dev/doc/start?lang=gitlab#usage
• other ideas?

/CC @iterative/cml @julieg18 @rogermparent

[shcheklein]

Related iterative/dvc.org#759 - I hope it can be solved for both with a single solution.

[casperdcl]

though should be noted that iterative/dvc.org#759 is specifically about code snippets, whereas #70 includes text & general markdown

[0x2b3bfa0]

About interface options: given that we're probably going to serve static content, wouldn't it be better to keep it simple and use path components instead of GET parameters? Exempli gratia: cml.dev/doc/start/gitlab#usage like in developers.google.com/docs/api/quickstart/nodejs#further_reading

[casperdcl]

Exempli gratia

the example you link (/thing/lang0#heading) uses different HTML pages (lang0.html, lang1.html) rather than one HTML page with toggles (/thing?lang=lang0#heading).

[casperdcl]

Any word on this? Would be a super helpful feature for CML docs!

[casperdcl]

See e.g.

https://github.com/iterative/shtab/raw/docs/docs/index.md ➡️ https://docs.iterative.ai/shtab/

=== "GitHub"

    *bla bla* standard markdown...

    ```yml
    - uses: iterative/setup-cml@v1
    ```

=== "GitLab"

    ...

[julieg18]

Any word on this? Would be a super helpful feature for CML docs!

Looking at our doc engine, I think this is possible!

[julieg18]

A couple questions about this task:

1. Have we decided on an interface option? Using html tags will probably be easiest to implement since our doc engine already allows us to easily turn any html tag into a custom React component.
2. Currently cml.dev uses local storage to save the user's selected language. Should we keep using that or implement a url interface?
3. Do we want to reuse the design on the main page or do we want to use a different design for this feature?

[casperdcl]

1. idk, tabbed looks like a cleaner interface and I've linked to the source so perhaps you could check if it's straightforward to integrate?
2. advantage of local storage is memory across pages. However I think URL is more important for sharing purposes. Could have both (i.e. auto-suffix all URLs if a lang is selected)?
3. the main page switch seems a bit too bold for docs... maybe less distracting like tabbed instead?

[julieg18]

1. idk, tabbed looks like a cleaner interface and I've linked to the source so perhaps you could check if it's straightforward to integrate?
2. advantage of local storage is memory across pages. However I think URL is more important for sharing purposes. Could have both (i.e. auto-suffix all URLs if a lang is selected)?
3. the main page switch seems a bit too bold for docs... maybe less distracting like tabbed instead?

1. I'll look into it! If we can't use that particular source, there might be an alternative somewhere.
2. Makes sense! We should be able to auto suffix URLs.
3. 👍

[julieg18]

As far as I can tell, we can't use tabbed since it's an extension designed for python-markdown. I also can't seem to find a JS based package that would enable tabbed content in markdown pages. The only way I can think of to use the tabbed syntax is to inspect the tabbed source code and create a plugin that does this in gatsby. @rogermparent, what do you think?

[0x2b3bfa0]

the main page switch seems a bit too bold for docs... maybe less distracting like tabbed instead?

Well, if we're going to add many dynamic sections and all of them need to be synchronized to the user choice, having some sort of global switch/dropdown doesn't seem that crazy (?)

If we choose to offer a tabbed interface for each dynamic section, we would need to synchronize them so users don't have to repeat their choices each time they hit one of these blocks.

[casperdcl]

tabbed

• the === is actually rst-syntax which the extension adds support for within markdown
• the extension (written in Python) then generates HTML for these tabs
• the generated HTML uses radio buttons + CSS
• as per my recent feature request, it then uses a little JS to "link" multiple sets on a page. As mentioned, we'd need local storage to link across multiple pages

General notes

Also for CML, we have loads of options: ci={GH,GL,BB}, cloud={aws,azure,gcp,k8s,self-hosted}, and even storage={s3,...} so I wouldn't really bother too much about multi-page links or top-of-page toggles for now.

[julieg18]

I decided to go ahead and use html tags for now and look into creating a gatsby plugin for using the === syntax at a later date. So far, I've created some basic markdown tabs, but I'm still working on a way to link multiple sets on a page(the JS code used in tabbed doesn't work correctly in React):

Markdown for tabs:

<toggle>
<tab title="Tab 1">

Suspendisse vulputate quis tellus vitae dapibus. Vestibulum sit amet gravida
dolor. Curabitur erat lectus, aliquet vitae orci convallis, varius iaculis
mauris. Suspendisse sed tellus dolor. `Cras` in fringilla dui, vel malesuada
libero. Aliquam erat volutpat. Aliquam a felis eros. Sed sagittis felis eu massa
condimentum molestie. Etiam non pellentesque arcu. Donec sit amet elit justo.
Curabitur maximus, ipsum ac pulvinar varius, tortor neque tempus arcu, ac
tincidunt ipsum leo a mauris. Quisque sagittis augue non augue tincidunt semper.
Sed tortor lorem, pellentesque ac pretium eu, facilisis at neque.

</tab>
<tab title="Tab 2">

Curabitur bibendum massa et leo mattis cursus. Phasellus eu feugiat velit, sit
amet commodo metus. Duis ante tortor, rhoncus vel risus eu, ultrices dignissim
sapien. Maecenas at nisl vitae risus tincidunt varius id sit amet urna. Aenean
blandit augue tellus, vel mattis sapien accumsan vitae. Mauris mollis enim ut
justo dictum auctor. Integer sed nisl sit amet **metus varius fringilla**. Morbi
sit amet sollicitudin dui, nec egestas erat. Donec ullamcorper nulla mauris, non
volutpat nisi consectetur sit amet. Duis quis feugiat lacus, vitae venenatis
eros. Aliquam enim odio, vulputate a egestas sed, malesuada vel mauris. Fusce
efficitur feugiat purus eget convallis. Nam vulputate pretium nisi vel
porttitor. Duis pretium bibendum congue.

</tab>
<tab title="Tab 3">

Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia
curae; In pellentesque dolor dui, nec viverra augue interdum quis. Vestibulum
mattis dui at sapien egestas, non ornare _lacus convallis_. Pellentesque et
gravida elit. Integer volutpat ligula eu lorem commodo blandit. Maecenas eu
lobortis felis, eu cursus mi. Maecenas nisi enim, vehicula sit amet tellus
efficitur, vehicula bibendum nunc. Donec sed sollicitudin dolor. Curabitur
aliquam metus sed arcu fringilla, ac lobortis odio varius. Suspendisse at elit
justo. Praesent in dictum leo. Vestibulum nec sapien at tortor molestie
imperdiet.

</tab>
</toggle>

tabs in action:

Screen.Recording.2021-09-24.at.9.13.17.PM.mov

[jorgeorpinel]

Related: iterative/dvc.org#759