Cassandra Targett created SOLR-11584:
----------------------------------------
Summary: Ref Guide: support more bootstrap components like tabs
and more
Key: SOLR-11584
URL: https://issues.apache.org/jira/browse/SOLR-11584
Project: Solr
Issue Type: Improvement
Security Level: Public (Default Security Level. Issues are Public)
Components: documentation
Reporter: Cassandra Targett
Assignee: Cassandra Targett
Priority: Minor
Fix For: 7.2
The theme I initially copied as the basis for the new Ref Guide included a
Bootstrap integration, which has the potential to provide us with a number of
options, such as organizing some content on a page into tabs (to present the
same information in multiple ways - such as Windows vs Unix commands, or
hand-editing schema.xml/managed-schema vs Schema API examples).
However, the way AsciiDoctor content is inserted into a Jekyll template made it
difficult to know how to use some of Bootstrap's features. Particularly since
we have to make sure whatever we put into the content comes out right in the
PDF.
I had a bit of a breakthrough on this, and feel confident we can make
straightforward instructions for anyone who might want to add this feature to
their content. A patch will follow shortly with more details but the summary is:
* Add an AsciiDoctor passthrough block that includes the Bootstrap HTML code to
create the tabs.
** This has an {{ifdef::backend-html5[]}} rule on it, so it will only be used
if the output format is HTML. The PDF will ignore this section entirely.
* Use AsciiDoctor's "role" support to name the proper class names, which
AsciiDoctor will convert into the right {{<div>}} elements in the HTML.
** These will take multiple class names and a section ID, which is perfect for
our needs.
** One caveat is the divs need to be properly nested, and must be defined on
blocks so all the content is inserted into the tab boxes appropriately. This
gets a little complicated because you can't nest blocks of the same type (yet),
but I found two block types we aren't using otherwise.
** The PDF similarly ignores these classes and IDs because it doesn't know what
to do with custom classes (but in the future these may be supported and we
could define these in a special way if we want).
* Modify some of the CSS to display the way we want since AsciiDoctor inserts
some of its own classes between the defined classes and the inheritance needs
to be set up right. Also the default styling for the blocks needs to be changed
so it doesn't look strange.
I'll include a patch with a sample file that has this working, plus detailed
instructions in the metadocs. In the meantime, I've attached a screenshot that
shows a small snippet from my testing.
While the focus here is using tabs & pills, we will be able to use the same
principles to support collapsing sections if that's preferred for presentation.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
