How to Contribute to Solr Documentation

Bold

Put asterisks around text to make it bold.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

Italics

Use underlines on either side of a string to put text into italics.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

Headings

Equal signs (=) are used for heading levels. Each equal sign is a level. Each page can only have one top level (i.e., only one section with a single =).

Levels should be appropriately nested. During the build, validation occurs to ensure that level 3s are preceded by level 2s, level 4s are preceded by level 3s, etc. Including out-of-sequence heading levels (such as a level 3 then a level 5) will not fail the build, but will produce an error.

More info: http://asciidoctor.org/docs/user-manual/#sections

Source Block Syntax Highlighting

The HTML output uses Rouge to add syntax highlighting to code examples. This is done by adding the language of the code block after the source, as shown in the above example source block (xml in that case).

Rouge has a long selection of lexers available. You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers. Use one of the valid short names to get syntax highlighting for that language.

Ideally, we will have an appropriate lexer to use for all source blocks, but that’s not possible. When in doubt, choose text, or leave it blank.

Importing Code Snippets from Other Files

The build system has the ability to "include" snippets located in other files — even non-AsciiDoc files such as *.java source code files.

Snippets are bounded by "tag" comments placed at the start and end of the section you would like to import. Opening tags look like: // tag::snippetName[]. Closing tags follow the format: // end::snippetName[]. Snippets can be dropped into an .adoc file using an include directive, following the format: include::PathToFileWithSnippet[tag=snippetName]. Note that when relative paths are provided in these directives, those paths are resolved relative to the location of the AsciiDoc file that the include appears in.

Snippets can be included directly from any file in the Lucene/Solr GIT repo by refering to a solr-root-path variable prior to the file path, for example:

[source,java,indent=0]
----
include::{solr-root-path}core/src/java/org/apache/solr/core/SolrCore.java[tag=something]
----

When building the Guide, the solr-root-path attribute will be automatically set correctly for the (temporary) build/solr-ref-guide/content directory used by Ant.

In order for editors (such as ATOM) to be able to offer "live preview" of the *.adoc files using these includes, the solr-root-path attribute must also be set as a document level attribute in each file, with the correct relative path.

For example, using-solrj.adoc sets solr-root-path in its header, along with an example-source-dir attribute (that depends on solr-root-path) in order to reduce redundancy in the many include:: directives it specifies…​

= Using SolrJ
:solr-root-path: ../../
:example-source-dir: {solr-root-path}solrj/src/test/org/apache/solr/client/ref_guide_examples/
...
[source,java,indent=0]
----
include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-solrclient-timeouts]
----
...
[source,java,indent=0]
----
include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-other-apis]
----
...

For more information on the include directive, see the documentation at http://asciidoctor.org/docs/user-manual/#include-partial.

Block Titles

Titles can be added to most blocks (images, source blocks, tables, etc.) by simply prefacing the title with a period (.). For example, to add a title to the source block example above:

.Example ID field
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />

Link to Sites on the Internet

When converting content to HTML, Asciidoctor will automatically render many link types (such as http: and mailto:) without any additional syntax.

However, you can add a name to a link by adding the URI followed by square brackets:

http://lucene.apache.org/solr[Solr Website]

Link to Other Pages/Sections of the Guide

A warning up front, linking to other pages can be a little bit painful. There are slightly different rules depending on the type of link you want to create, and where you are linking from.

The build process includes a validation for internal or inter-page links, so if you can build the docs locally, you can use that to verify you constructed your link properly (or pay attention to the Jenkins build after your commit).

With all of the below examples, you can add text to display as the link title by adding a comma after the section reference followed by the display text, as in:

<<schema-api.adoc#modify-the-schema,Modify the Schema>>

Unordered Lists

Simple bulleted lists need each line to start with an asterisk (*). It should be the first character of the line, and be followed by a space.

These lists also need to be separated from the

More info: http://asciidoctor.org/docs/user-manual/#unordered-lists

Ordered Lists

Numbered lists need each line to start with a period (.). It should be the first character of the line, and be followed by a space.

This style is preferred over manually numbering your list.

More info: http://asciidoctor.org/docs/user-manual/#ordered-lists

Labeled Lists

These are like question & answer lists or glossary definitions. Each line should start with the list item followed by double colons (::), then a space or new line.

Labeled lists can be nested by adding an additional colon (such as :::, etc.).

If your content will span multiple paragraphs or include source blocks, etc., you will want to add a plus sign (+) to keep the sections together for your reader.

More info: http://asciidoctor.org/docs/user-manual/#labeled-list

Basic Tables

The basic structure of a table is similar to Markdown, with pipes (|) delimiting columns between rows:

|===
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Note the use of |=== at the start and end. For basic tables that’s not exactly required, but it does help to delimit the start and end of the table in case you accidentally introduce (or maybe prefer) spaces between the rows.

Header Rows

To add a header to a table, you need only set the header attribute at the start of the table:

[options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Defining Column Styles

If you need to define specific styles to all rows in a column, you can do so with the attributes.

This example will center all content in all rows:

[cols="2*^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Alignments or any other styles can be applied only to a specific column. For example, this would only center the last column of the table:

[cols="2*,^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Many more examples of formatting:

More Options

Tables can also be given footer rows, borders, and captions. You can determine the width of columns, or the width of the table as a whole.

CSV or DSV can also be used instead of formatting the data in pipes.

More info: http://asciidoctor.org/docs/user-manual/#tables

Doc Preview

This allows you to see your document in something close to what it might appear like when output to HTML.

The following information is from http://asciidoctor.org/docs/editing-asciidoc-with-live-preview.

Jekyll-Asciidoctor Plugin

We use a plugin for Jekyll from the Asciidoctor project to integrate Jekyll with Asciidoc formatted content. The source for the plugin is available at https://github.com/asciidoctor/jekyll-asciidoc.

This plugin allows us to use Asciidoctor-style variables with Jekyll.

_config.yml

The _config.yml is a global configuration file that drives many of the options used when building the site (particularly in our use of Jekyll).

We have template-ized _config.yml, so in our use of Jekyll you will find it in solr/solr-ref-guide/src as _config.yml.template. This allows us to define some variables during the build and use common Lucene/Solr build parameters (such as project versions).

Front Matter

Front matter for Jekyll is similar to a header that defines the title of the page, and other variables that may be helpful (or even required) when rendering the page.

Every document that will be converted to HTML must include at least the page title at the top of the page. Page titles are defined with a single equal sign (=) followed by the title that will appear at the top of the page (such as = Topic of the Page).

Many guides to Jekyll also say that defining the layout in the front matter is required. However, since we only use one layout for all pages, we have defined this as a default.

The Solr Ref Guide uses the front matter to define some custom attributes on a per-page basis:

Other page-level elements can also be defined, such as an Asciidoctor attribute that should apply only to that page, but are not needed on a regular basis.

The format for adding any parameter to the front matter is to use colons on both sides of the parameter, followed by the value for the parameter (such as :page-toc: false).

Layouts

Layouts define the "look and feel" of each page. Jekyll uses Liquid for page templates.

For our implementation of Jekyll, layouts are found in solr-ref-guide/src/_layouts.

We currently use the _layouts/default.html layout for overall page structure, for almost all pages and _layouts/page.html for the page-level content. The page.html layout is inserted into the default.html layout.

The main page (index.html) of the Ref Guide uses the _layouts/home.html layout. It also still uses _layouts/page.html for the page-level content. This is done because index.html has some special formatting and rules for how to define the page.

Includes

Include files are (usually) small HTML files that are pulled into a layout when a page is being built. They are Liquid templates that define an area of the page. This allows flexibility across layouts - all pages can have the same header without duplicating code, but different pages could have different menu options.

Include files that we use define the top navigation, the page header, and the page footer.

For our implementation of Jekyll, include files are found in solr-ref-guide/src/_includes.

Data Files

Data files include data such as lists that should be included in each page. The left-hand navigation menu is an example of a data file. However, in our build, the navigation is built from the page-children hierarchies defined on parent pages.

For our implementation of Jekyll, data files are found in solr-ref-guide/src/_data.

Asciidoctor Slim Templates

Jekyll creates all of the page elements we do not define in each .adoc file: the header, footer, top nav, sidebar nav, and other parts of the page that we don’t worry about as we write the content of a page.

Asciidoctor converts the content in each .adoc file into HTML and inserts it into the Jekyll page layout we have defined (see Layouts) to make the individual HTML files that make up the Ref Guide.

While we have unlimited control over styling page content via CSS, without creating custom Asciidoctor-specific plugins or templates there is little out-of-the-box control over the elements, classes, etc. that make up the HTML pages.

In order to better support HTML5, we have customized Asciidoc’s default conversion with templates found in the _templates directory. These templates use Slim as the template engine.

Since these templates dictate the very structure of the HTML of our content, customizing these should only be attempted in rare instances and with extensive testing for unforeseen impacts.

Using Bootstrap

The HTML files include Bootstrap (v4.1.3 as of April 2020, see _includes/head.html to confirm the Bootstrap version currently being used), so all of the components of Bootstrap are available.

The design of the Ref Guide makes extensive use of Bootstrap classes to layout the page via the Liquid templates and our customized Asciidoctor templates.

When we want to use additional components of Boostrap that require specific HTML constructs, we must define those within the page content itself (using either <div> elements in the content or with Asciidoctor’s roles, discussed in the section).

<ul class="nav nav-pills"> 
  <li class="active"><a data-toggle="pill" href="#sec1">Section 1</a></li>
  <li><a data-toggle="pill" href="#sect2">Section 2</a></li>
</ul>

<div class="tab-content"> 
  <div id="sect1" class="tab-pane active"> 
    <h3>Section 1</h3>
    <p>Some content.</p>
  </div>
  <div id="sect2" class="tab-pane">
    <h3>Section 2</h3>
    <p>Some other content.</p>
  </div>
</div>

Build Validation

When you run ant build-site to build the HTML, several additional validations occur during that process. See solr-ref-guide/tools/CheckLinksAndAnchors.java for details of what that tool does to validate content.

Update DRAFT for Release

Since the Guide has already been uploaded to SVN, you need to overwrite the existing files in svn with a version of the production version of the guide:

Build Production Guide

Build the Guide locally with a parameter for the Guide version. This requires the same pre-requisites from above.

$ant clean default -Dsolr-guide-version=X.Y

where X.Y is the version you want to publish (i.e., 7.7).

Pull Production Repo and Upload New Files

Verify Upload Successful

Spot-check a few pages to verify that the DRAFT watermark is gone, and also that Solr Javadocs link back to Lucene’s correctly (the UpdateRequestProcessor page has a lot of Javadoc links).

Make a link to the new Version from website

The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide.

Edit guide.md in staging

Publish the changes to production

You can use your favourite git client to merge master into branch production. Or you can use GitHub website:

The ordinary Solr release process will update the LUCENE_LATEST_RELEASE property of the website, which will ensure that Ref Guide URLs without a version in the path (e.g., /solr/guide/mypage.adoc) will automatically redirect to the latest Guide.