Create linked-tabs widget for displaying platform-specific instructions

[dedemorton]

We need a better way of displaying platform-specific instructions (especially commands) in the docs.

It would be nice to have a widget with tabs or some other mechanism that allows users to select a platform and see the correct commands/instructions for that platform.

---

elastic/beats#17007 added lots of custom pass-through HTML to support linked tab widgets.

Add an Asciidoctor extension/directive to make it easier to create these on a page.

Depends on #1895

[sophiec20]

+1

[dedemorton]

@nik9000 I'm wondering if we can get some traction on this. For Beats, we provide users with platform-specific commands for getting started, but as we add more ways to install/manage beats, our instructions are getting very long...for very simple tasks.

I would rather have a design that's really slick, but we've been waiting for a redesign of the website for years now.

EDITED: I removed my example because it's such a hack I don't want to put it out in the wild.

[nik9000]

I'm still on vacation for a next two weeks but some kind of platform selecting widget does sound like a good idea to me.

…

On Fri, Jun 21, 2019, 20:55 DeDe Morton ***@***.***> wrote: @nik9000 <https://github.com/nik9000> I'm wondering if we can get some traction on this. For Beats, we provide users with platform-specific commands for getting started, but as we add more ways to install/manage beats, our instructions are getting very long...for very simple tasks. I'd love to see something slick, but even a crude tabbed widget would be better than what we have now. I mocked one up in HTML in about 20 min. Not proposing that we use this, but it is possible to get something just by wrapping content in HTML (in this case, radio buttons!) and adding some CSS styles: https://oswidget-9b394.firebaseapp.com/packetbeat-starting.html My example is not meant to be good design, and it won't work on older browsers, but it does show that we can do something like this with HTML and CSS changes. I would rather have something really slick, but we've been waiting for a redesign of the website for years now. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#260?email_source=notifications&email_token=AABUXIV26TYEFU43TGUVOXLP3WIBZA5CNFSM4EELNOR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODYJ6OZI#issuecomment-504620901>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABUXIT75IF4QZNIYJ5MXD3P3WIBZANCNFSM4EELNORQ> .

[dedemorton]

@gtback This is one of the enhancements that we need for solution-based docs.

@bmorelli25 Created a basic prototype that demonstrates the kind of mechanism we need:
elastic/apm-server#3556

Brandon recently pointed me towards an asciidoctor extension that adds tabs, but I don't know how difficult it would be to use this in our current build environment.

• https://stackoverflow.com/questions/38211766/using-tabs-in-asciidoc-spring-rest-docs
• https://github.com/spring-io/spring-asciidoctor-extensions/blob/master/README.adoc

Can you take a look and see if it's feasible to add this extension to our build somehow?

I've been waiting for a long time for this enhancement. I hope we can get some traction soon

[gtback]

@dedemorton Part of the reason for the complexity of the current approach for code snippets is that content is sourced from other repos (generally, Elasticsearch client libraries). Would that be the case here, or would it be (like in @bmorelli25's example) all drawn from the current repo and just using tabs as a visual/UX improvement?

I don't know we could use that extension directly, because it seems to be targeting the Java implementation of Asciidoctor, but I'm sure we could find (or write) something similar ourselves, or even adapt and reuse the existing widget if it's OK.

[dedemorton]

Would that be the case here, or would it be (like in @bmorelli25's example) all drawn from the current repo and just using tabs as a visual/UX improvement?

For Beats, everything lives in one repo right now. That might change as we roll out some of the content reuse we've discussed.

So ... did a little experimenting yesterday and came up with a prototype for Beats based on the work that @bmorelli25 did for APM: My changes are mixed in with other content changes that are in progress. And I offer the disclaimer that I'm not a web developer, but here it is:

elastic/beats#17007 (widget code is under docs/tab-widgets).

I used Brandon's code and slapped a different CSS on it. The CSS was lifted from W3C schools, but I figured we would want to replace it with our own styles anyhow.

Again, I kind of hacked this together. Ideally we would want the build to generate the widget code based on information that's specified in the tagged regions.

I wonder if we can use this hacky way forward for now and plan to replace it with something that's more automated. The main requirement, I guess, would be that we find a way to use the tagged regions. That would help us avoid any rework.

[dedemorton]

Update on the tabbed panels in the Beats documentation:

For now, we are maintaining the tabbed panel code manually and injecting it into the HTML files. I just merged a PR that introduces the widgets here: elastic/beats#17007. They are going into the 7.9 release.

It would be great at some point to be able to generate these widgets.

[dedemorton]

We are considering our "widget" code (seen here) to be experimental until we figure out the next steps. We need to get some of this figured out before propagating these widgets to more pages:

• Get design/developer resources to improve the javascript and css code. Right now, the tabbed panels display fine on desktop browsers, but aren't optimized for mobile (though that's true of our docs, too).
• Add styles to the stylesheet used by the guide (right now we include the the css on each HTML page).
• Add logic to the doc build to automate the creation of widgets, or at least add some kind of validation to the PR builds.
• (nice-to-have) Add a copy button for copying commands displayed in the tabs.