lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Cassandra Targett (JIRA)" <j...@apache.org>
Subject [jira] [Created] (SOLR-11584) Ref Guide: support more bootstrap components like tabs and more
Date Tue, 31 Oct 2017 18:53:00 GMT
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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message