You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2020/04/01 21:04:01 UTC
[lucene-solr] branch jira/solr-14173-2 updated: Update docs for
missing Jekyll features added; remove overlapping section headings
This is an automated email from the ASF dual-hosted git repository.
ctargett pushed a commit to branch jira/solr-14173-2
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
The following commit(s) were added to refs/heads/jira/solr-14173-2 by this push:
new 335251b Update docs for missing Jekyll features added; remove overlapping section headings
335251b is described below
commit 335251b6bf73484295364154a8cd68f9b8631371
Author: Cassandra Targett <ca...@lucidworks.com>
AuthorDate: Wed Apr 1 16:03:05 2020 -0500
Update docs for missing Jekyll features added; remove overlapping section headings
---
solr/solr-ref-guide/src/how-to-contribute.adoc | 13 ++++------
solr/solr-ref-guide/src/meta-docs/jekyll.adoc | 34 +++++++++++++++++---------
solr/solr-ref-guide/src/meta-docs/publish.adoc | 4 +--
3 files changed, 30 insertions(+), 21 deletions(-)
diff --git a/solr/solr-ref-guide/src/how-to-contribute.adoc b/solr/solr-ref-guide/src/how-to-contribute.adoc
index 1c8ee60..f13b011 100644
--- a/solr/solr-ref-guide/src/how-to-contribute.adoc
+++ b/solr/solr-ref-guide/src/how-to-contribute.adoc
@@ -25,16 +25,13 @@ The following sections give an overview of how to work with AsciiDoc-format file
Once you have a patch you'd like to contribute, you can submit it with a JIRA issue, the same as any other patch. See also the Solr wiki section on https://cwiki.apache.org/confluence/display/solr/HowToContribute[How To Contribute] for information on submitting patches.
-== Working with AsciiDoc Files
-include::meta-docs/asciidoc-syntax.adoc[leveloffset=+2]
+// These pages cover AsciiDoc syntax and tools
+include::meta-docs/asciidoc-syntax.adoc[leveloffset=+1]
-include::meta-docs/editing-tools.adoc[leveloffset=+2]
+include::meta-docs/editing-tools.adoc[leveloffset=+1]
-== Modifying the HTML Templates
-The Solr Reference Guide is published in HTML format, using Jekyll and some plugins.
+// This covers our Jekyll templates
+include::meta-docs/jekyll.adoc[leveloffset=+1]
-include::meta-docs/jekyll.adoc[leveloffset=+2]
-
-== How to Publish the Guide
// This is the how to publish section:
include::meta-docs/publish.adoc[leveloffset=+1]
diff --git a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
index 28e46b7..2253607 100644
--- a/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
+++ b/solr/solr-ref-guide/src/meta-docs/jekyll.adoc
@@ -1,4 +1,4 @@
-= Making Changes to Jekyll
+= Working with HTML Templates
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
@@ -47,7 +47,7 @@ Every document that will be converted to HTML *must* include at least the page t
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:
+The Solr Ref Guide uses the front matter to define some custom attributes on a per-page basis:
* `page-children` - ordered list of child pages, this is used to build the site navigation menu that appears to the left of each page's content.
@@ -96,19 +96,25 @@ However, in our build, the navigation is built from the `page-children` hierarch
For our implementation of Jekyll, data files are found in `solr-ref-guide/src/_data`.
-=== Using Bootstrap Components
+=== Asciidoctor Slim Templates
-The HTML files include https://getbootstrap.com/docs/3.3/[Bootstrap] (v3.3.4 as of October 2017, see `_includes/head.html` to confirm the Bootstrap version currently being used), so all of the components of Bootstrap are available.
+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.
-However, before trying to use these components, it's important to understand how Jekyll and Asciidoctor relate to one another.
+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.
-==== How Jekyll Consumes .adoc Files
+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.
-Jekyll creates all of the page elements we do not define in an `.adoc` file: the header, footer, navigation elements, comments, and other parts of the page that we don't worry about as we write the content of a page. It produces a template that our content is inserted into.
+In order to better support HTML5, we have customized Asciidoc's default conversion with templates found in the `_templates` directory. These templates use http://slim-lang.com/[Slim] as the template engine.
-Asciidoctor converts our content to HTML - defining its own classes to define default styling - and inserts it into the template Jekyll has provided. While we have a lot of control over the CSS for styling, without creating custom plugins for Asciidoctor, we don't control the HTML elements produced by the plugin.
+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.
-This is important because in order to use Bootstrap components, we need to insert `div` classes into the HTML produced by Asciidoctor.
+=== Using Bootstrap
+
+The HTML files include https://getbootstrap.com/docs/4.1/[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).
==== Asciidoctor Roles
@@ -118,10 +124,12 @@ Asciidoctor does not call these "divs" or "classes", but instead "_roles_". We c
Because roles are so flexible, they only apply to the thing - the word, content block, image, etc. - they are directly applied to. This means that if we want an entire section of content to be given a specific role in the HTML (i.e., enclosed in a `<div>`), then we need to put the content in a block.
+TIP: For more on Roles in Asciidoctor, see https://asciidoctor.org/docs/user-manual/#role[Role] in the Asciidoctor User Guide.
+
==== Creating Tabbed Sections
Hopefully a little bit of background on roles is helpful to understanding the rest of what we'll do to create a tabbed section in a page.
-See the Bootstrap docs on https://getbootstrap.com/docs/3.3/components/#nav-tabs[tabs] for details on how to use tabs and pills with Bootstrap. As a quick overview, tabs in Bootstrap are defined like this:
+See the Bootstrap docs on https://getbootstrap.com/docs/4.1/components/navs/#tabs[nav tabs] for details on how to use tabs and pills with Bootstrap. As a quick overview, tabs in Bootstrap are defined like this:
[source,html]
----
@@ -198,10 +206,14 @@ My content...
== Building the HTML Site
-An Ant target `build-site` will build the full HTML site. This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
+An Ant target `ant build-site` when run from the `solr/solr-ref-guide` directory will build the full HTML site (found in `solr/build/solr-ref-guide/html-site`).
+
+This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
Building the HTML has several dependencies that will need to be installed on your local machine. Review the `README.adoc` file in the `solr/solr-ref-guide` directory for specific details.
+Using the Gradle build does not require any local dependencies. Simply use `./gradlew buildSite` to generate the HTML files using Gradle (these will be found in `solr/solr-ref-guide/build/html-site`).
+
=== 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.
diff --git a/solr/solr-ref-guide/src/meta-docs/publish.adoc b/solr/solr-ref-guide/src/meta-docs/publish.adoc
index a246d8f..0f1a5e9 100644
--- a/solr/solr-ref-guide/src/meta-docs/publish.adoc
+++ b/solr/solr-ref-guide/src/meta-docs/publish.adoc
@@ -60,7 +60,7 @@ svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-gu
Confirm you can browse to Guide manually by going to the new URL. For example:
https://lucene.apache.org/solr/guide/7_7
-== Publish the Guide
+== Publish the Final Guide
There are two steps to publishing the Guide: first, uploading the DRAFT pages with the production-ready version; and second, updating links to point to the new Guide.
@@ -116,4 +116,4 @@ You can use your favourite git client to merge master into branch `production`.
. Note: If there are other changes staged, you will see those as well if you merge `master` into `production`
. Click the "Merge" button on the PR
-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.
\ No newline at end of file
+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.