You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@solr.apache.org by ep...@apache.org on 2022/02/11 19:44:34 UTC
[solr] 10/13: 15556: Migrate the Ref Guide to use Antora (#605)
This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
commit ea0e3bc85ee92243373d113ab039f73a2807da28
Author: Houston Putman <ho...@apache.org>
AuthorDate: Thu Feb 10 12:19:48 2022 -0500
15556: Migrate the Ref Guide to use Antora (#605)
Co-authored-by: Cassandra Targett <ct...@apache.org>
Co-authored-by: Mike Drob <md...@apache.org>
---
dev-docs/ref-guide/antora.adoc | 70 +
dev-docs/ref-guide/asciidoc-syntax.adoc | 78 +-
dev-docs/ref-guide/jekyll.adoc | 136 -
dev-docs/ref-guide/publish.adoc | 131 -
gradle/documentation/pull-lucene-javadocs.gradle | 6 +-
gradle/validation/ecj-lint.gradle | 8 -
gradle/validation/rat-sources.gradle | 6 +-
gradle/validation/validate-source-patterns.gradle | 11 +-
solr/.gitignore | 2 +
solr/solr-ref-guide/README.adoc | 7 +-
solr/solr-ref-guide/antora.template.yml | 36 +
solr/solr-ref-guide/antora.yml | 36 +
solr/solr-ref-guide/build.gradle | 643 ++--
.../ROOT}/images/Solr_Logo_on_white.png | Bin
.../ROOT}/images/diagrams/splitshard-seq.png | Bin
.../ROOT}/images/diagrams/splitshard-seq.puml | 0
.../ROOT}/images/draft-background.png | Bin
.../ROOT}/images/icons/bullet_blue.gif | Bin
.../images/icons/contenttypes/home_page_16.png | Bin
.../ROOT}/images/icons/emoticons/warning.png | Bin
.../{src => modules/ROOT}/images/icons/favicon.ico | Bin
.../ROOT}/images/solr-sunOnly-small.png | Bin
solr/solr-ref-guide/modules/ROOT/pages/index.adoc | 50 +
.../modules/configuration-guide/config-nav.adoc | 40 +
.../images/configuration-files/files-screen.png | Bin
.../index-segments-merging/segments_info.png | Bin
.../configuration-guide/pages/caches-warming.adoc | 343 ++
.../pages}/cluster-plugins.adoc | 0
.../configuration-guide/pages/codec-factory.adoc | 58 +
.../configuration-guide/pages/collections-api.adoc | 303 ++
.../pages/commits-transaction-logs.adoc | 322 ++
.../configuration-guide/pages/config-api.adoc | 933 +++++
.../configuration-guide/pages/config-sets.adoc | 102 +
.../configuration-guide/pages/configsets-api.adoc | 386 ++
.../pages/configuration-files.adoc | 107 +
.../pages/configuring-solr-xml.adoc | 593 +++
.../pages/configuring-solrconfig-xml.adoc | 75 +
.../configuration-guide/pages/core-discovery.adoc | 219 ++
.../configuration-guide/pages/coreadmin-api.adoc | 728 ++++
.../pages/implicit-requesthandlers.adoc | 387 ++
.../pages/index-location-format.adoc | 65 +
.../pages/index-segments-merging.adoc | 380 ++
.../configuration-guide/pages/initparams.adoc | 137 +
.../modules/configuration-guide/pages/libs.adoc | 75 +
.../pages/managed-resources.adoc | 314 ++
.../pages}/package-manager-internals.adoc | 0
.../configuration-guide/pages/package-manager.adoc | 210 ++
.../pages/property-substitution.adoc | 146 +
.../configuration-guide/pages/realtime-get.adoc | 222 ++
.../pages}/replica-placement-plugins.adoc | 0
.../pages/request-parameters-api.adoc | 230 ++
.../pages/requestdispatcher.adoc | 212 ++
.../pages/requesthandlers-searchcomponents.adoc | 330 ++
.../pages/resource-loading.adoc | 46 +
.../configuration-guide/pages/schema-factory.adoc | 133 +
.../pages/script-update-processor.adoc | 297 ++
.../configuration-guide/pages/solr-modules.adoc | 41 +
.../configuration-guide/pages/solr-plugins.adoc | 67 +
.../pages/update-request-processors.adoc | 494 +++
.../configuration-guide/pages}/v2-api.adoc | 0
.../modules/deployment-guide/deployment-nav.adoc | 76 +
.../examples/UsingSolrJRefGuideExamplesTest.java | 1 +
.../examples/ZkConfigFilesTest.java | 1 +
.../images/cloud-screens/cloud-graph.png | Bin
.../images/cloud-screens/cloud-hover.png | Bin
.../images/cloud-screens/cloud-nodes.png | Bin
.../images/cloud-screens/cloud-tree.png | Bin
.../images/cloud-screens/cloud-zkstatus.png | Bin
.../images/collections-core-admin/DeleteShard.png | Bin
.../collections-core-admin/collection-admin.png | Bin
.../images/configuring-logging/level_menu.png | Bin
.../images/configuring-logging/logging.png | Bin
.../distributed-tracing/query-request-tracing.png | Bin
.../images/installing-solr/SolrAdminDashboard.png | Bin
.../images/jvm-settings/javaproperties.png | Bin
.../grafana-solr-dashboard.png | Bin
.../prometheus-solr-ping.png | Bin
.../solr-exporter-diagram.png | Bin
.../deployment-guide}/images/ping/ping.png | Bin
.../plugins-stats-screen/plugin-searcher.png | Bin
.../images/security-ui/add-permission.png | Bin
.../images/security-ui/edit-user-dialog.png | Bin
.../images/security-ui/filter-users.png | Bin
.../images/security-ui/permissions.png | Bin
.../deployment-guide}/images/security-ui/roles.png | Bin
.../security-ui/security-not-enabled-warn.png | Bin
.../deployment-guide}/images/security-ui/users.png | Bin
.../images/thread-dump/thread_dump_1.png | Bin
.../images/thread-dump/thread_dump_2.png | Bin
.../user-managed-index-replication/replication.png | Bin
.../user-managed-replication.png | Bin
.../deployment-guide/pages/alias-management.adoc | 746 ++++
.../modules/deployment-guide/pages/aliases.adoc | 359 ++
.../deployment-guide/pages}/audit-logging.adoc | 0
.../authentication-and-authorization-plugins.adoc | 224 ++
.../deployment-guide/pages/backup-restore.adoc | 796 +++++
.../pages/basic-authentication-plugin.adoc | 364 ++
.../pages/cert-authentication-plugin.adoc | 61 +
.../deployment-guide/pages}/circuit-breakers.adoc | 0
.../deployment-guide/pages/client-apis.adoc | 72 +
.../deployment-guide/pages/cloud-screens.adoc | 67 +
.../pages/cluster-node-management.adoc | 876 +++++
.../deployment-guide/pages}/cluster-types.adoc | 0
.../pages/collection-management.adoc | 2191 ++++++++++++
.../pages/collections-core-admin.adoc | 40 +
.../pages/configuring-logging.adoc | 159 +
.../pages/distributed-tracing.adoc | 79 +
.../modules/deployment-guide/pages/docker-faq.adoc | 346 ++
.../deployment-guide/pages}/docker-networking.adoc | 0
.../deployment-guide/pages/enabling-ssl.adoc | 446 +++
.../pages/hadoop-authentication-plugin.adoc | 223 ++
.../pages}/indexupgrader-tool.adoc | 0
.../deployment-guide/pages/installing-solr.adoc | 227 ++
.../modules/deployment-guide/pages/javascript.adoc | 30 +
.../deployment-guide/pages/jmx-with-solr.adoc | 78 +
.../deployment-guide/pages/jvm-settings.adoc | 84 +
.../pages/jwt-authentication-plugin.adoc | 274 ++
.../pages/kerberos-authentication-plugin.adoc | 547 +++
.../pages/mbean-request-handler.adoc | 84 +
.../deployment-guide/pages/metrics-reporting.adoc | 876 +++++
.../monitoring-with-prometheus-and-grafana.adoc | 569 +++
.../deployment-guide/pages}/node-roles.adoc | 0
.../pages/performance-statistics-reference.adoc | 222 ++
.../modules/deployment-guide/pages/ping.adoc | 92 +
.../pages/plugins-stats-screen.adoc | 30 +
.../modules/deployment-guide/pages/python.adoc | 71 +
.../deployment-guide/pages}/rate-limiters.adoc | 0
.../deployment-guide/pages/replica-management.adoc | 809 +++++
.../modules/deployment-guide/pages/ruby.adoc | 115 +
.../pages/rule-based-authorization-plugin.adoc | 583 +++
.../deployment-guide/pages/securing-solr.adoc | 118 +
.../deployment-guide/pages/security-ui.adoc | 107 +
.../deployment-guide/pages/shard-management.adoc | 626 ++++
.../pages/solr-control-script-reference.adoc | 1479 ++++++++
.../deployment-guide/pages/solr-in-docker.adoc | 349 ++
.../deployment-guide/pages/solr-on-hdfs.adoc | 290 ++
.../pages/solrcloud-distributed-requests.adoc | 462 +++
.../solrcloud-recoveries-and-write-tolerance.adoc | 0
.../pages/solrcloud-shards-indexing.adoc | 222 ++
.../solrcloud-with-legacy-configuration-files.adoc | 77 +
.../modules/deployment-guide/pages/solrj.adoc | 260 ++
.../pages}/system-requirements.adoc | 0
.../pages/taking-solr-to-production.adoc | 477 +++
.../deployment-guide/pages}/task-management.adoc | 0
.../deployment-guide/pages/thread-dump.adoc | 47 +
.../pages/upgrading-a-solr-cluster.adoc | 110 +
.../pages/user-managed-distributed-search.adoc | 124 +
.../pages/user-managed-index-replication.adoc | 524 +++
.../pages/zookeeper-access-control.adoc | 241 ++
.../deployment-guide/pages/zookeeper-ensemble.adoc | 552 +++
.../pages/zookeeper-file-management.adoc | 97 +
.../pages/zookeeper-utilities.adoc | 164 +
.../getting-started/getting-started-nav.adoc | 19 +
.../images/searching-in-solr/cnet-faceting.png | Bin
.../images/searching-in-solr/search-process.png | Bin
.../images/solr-admin-ui/Assistance.png | Bin
.../images/solr-admin-ui/collection_dashboard.png | Bin
.../images/solr-admin-ui/core_dashboard.png | Bin
.../images/solr-admin-ui/dashboard.png | Bin
.../images/solr-admin-ui/login.png | Bin
.../images/solr-admin-ui/schema-designer.png | Bin
.../images/solr-admin-ui/security.png | Bin
.../solr-tutorial/tutorial-add-copy-field.png | Bin
.../images/solr-tutorial/tutorial-add-field.png | Bin
.../tutorial-admin-ui-facet-options.png | Bin
.../images/solr-tutorial/tutorial-query-screen.png | Bin
.../images/solr-tutorial/tutorial-range-facet.png | Bin
.../images/solr-tutorial/tutorial-solrcloud.png | Bin
.../images/solr-tutorial/tutorial-spatial.png | Bin
.../images/tutorial-aws/aws-key.png | Bin
.../images/tutorial-aws/aws-security-create.png | Bin
.../images/tutorial-aws/aws-security-edit.png | Bin
.../getting-started/pages/about-this-guide.adoc | 93 +
.../pages/documents-fields-schema-design.adoc | 101 +
.../getting-started/pages/introduction.adoc | 43 +
.../getting-started/pages}/relevance.adoc | 0
.../getting-started/pages/searching-in-solr.adoc | 89 +
.../getting-started/pages/solr-admin-ui.adoc | 190 +
.../getting-started/pages/solr-glossary.adoc | 240 ++
.../getting-started/pages/solr-indexing.adoc | 59 +
.../getting-started/pages/solr-tutorial.adoc | 94 +
.../getting-started/pages/tutorial-aws.adoc | 305 ++
.../getting-started/pages/tutorial-diy.adoc | 110 +
.../getting-started/pages/tutorial-films.adoc | 462 +++
.../getting-started/pages/tutorial-solrcloud.adoc | 217 ++
.../pages/tutorial-techproducts.adoc | 509 +++
.../examples/IndexingNestedDocuments.java | 1 +
.../modules/indexing-guide/examples/stemdict.txt | 1 +
.../images/analysis-screen/analysis_compare_0.png | Bin
.../images/analysis-screen/analysis_compare_1.png | Bin
.../images/analysis-screen/analysis_compare_2.png | Bin
.../images/analysis-screen/analysis_compare_3.png | Bin
.../images/analysis-screen/analysis_compare_4.png | Bin
.../images/analysis-screen/analysis_normal.png | Bin
.../documents-screen/documents_add_screen.png | Bin
.../images/indexing-with-tika/sample-pdf-query.png | Bin
.../schema-browser-screen/schema_browser_terms.png | Bin
.../images/schema-designer/analyze-sample-docs.png | Bin
.../images/schema-designer/field-filters.png | Bin
.../images/schema-designer/incompat-change.png | Bin
.../images/schema-designer/new-schema.png | Bin
.../images/schema-designer/publish.png | Bin
.../images/schema-designer/query-tester.png | Bin
.../images/schema-designer/reload-schema.png | Bin
.../schema-designer/schema-editor-fields.png | Bin
.../images/schema-designer/schema-editor-root.png | Bin
.../schema-designer/schema-editor-update.png | Bin
.../images/schema-designer/show-changes.png | Bin
.../images/schema-designer/text-analysis.png | Bin
.../modules/indexing-guide/indexing-nav.adoc | 45 +
.../indexing-guide/pages/analysis-screen.adoc | 71 +
.../modules/indexing-guide/pages/analyzers.adoc | 186 +
.../indexing-guide/pages}/charfilterfactories.adoc | 0
.../indexing-guide/pages/content-streams.adoc | 94 +
.../modules/indexing-guide/pages/copy-fields.adoc | 67 +
.../pages/currencies-exchange-rates.adoc | 142 +
.../pages}/date-formatting-math.adoc | 0
.../indexing-guide/pages/de-duplication.adoc | 131 +
.../indexing-guide/pages/document-analysis.adoc | 58 +
.../indexing-guide/pages/documents-screen.adoc | 86 +
.../modules/indexing-guide/pages/docvalues.adoc | 118 +
.../indexing-guide/pages}/dynamic-fields.adoc | 0
.../indexing-guide/pages}/enum-fields.adoc | 0
.../pages/external-files-processes.adoc | 318 ++
.../pages/field-properties-by-use-case.adoc | 56 +
.../field-type-definitions-and-properties.adoc | 258 ++
.../pages/field-types-included-with-solr.adoc | 114 +
.../modules/indexing-guide/pages/fields.adoc | 76 +
.../modules/indexing-guide/pages/filters.adoc | 3761 ++++++++++++++++++++
.../pages/indexing-nested-documents.adoc | 534 +++
.../indexing-guide/pages/indexing-with-tika.adoc | 632 ++++
.../pages/indexing-with-update-handlers.adoc | 758 ++++
.../indexing-guide/pages/language-analysis.adoc | 3431 ++++++++++++++++++
.../indexing-guide/pages/language-detection.adoc | 296 ++
.../indexing-guide/pages/luke-request-handler.adoc | 120 +
.../pages/partial-document-updates.adoc | 545 +++
.../indexing-guide/pages/phonetic-matching.adoc | 140 +
.../modules/indexing-guide/pages/post-tool.adoc | 190 +
.../modules/indexing-guide/pages/reindexing.adoc | 174 +
.../modules/indexing-guide/pages/schema-api.adoc | 1653 +++++++++
.../pages/schema-browser-screen.adoc | 49 +
.../indexing-guide/pages/schema-designer.adoc | 237 ++
.../indexing-guide/pages/schema-elements.adoc | 158 +
.../indexing-guide/pages/schemaless-mode.adoc | 339 ++
.../modules/indexing-guide/pages/tokenizers.adoc | 916 +++++
.../transforming-and-indexing-custom-json.adoc | 927 +++++
.../JsonRequestApiHeatmapFacetingTest.java | 1 +
.../query-guide/examples/JsonRequestApiTest.java | 1 +
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_1.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_11.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_12.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_13.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_14.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_15.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_16.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_17.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_19.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_2.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_20.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_3.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_4.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_5.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_6.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_7.png | Bin
.../jdbc-dbvisualizer/dbvisualizer_solrjdbc_9.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_1.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_10.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_11.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_12.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_13.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_14.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_15.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_2.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_3.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_4.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_5.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_7.png | Bin
.../jdbc-squirrel/squirrelsql_solrjdbc_9.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_1.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_2.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_3.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_4.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_5.png | Bin
.../images/jdbc-zeppelin/zeppelin_solrjdbc_6.png | Bin
.../images/math-expressions/2Centroids.png | Bin
.../images/math-expressions/2DCluster1.png | Bin
.../images/math-expressions/2DCluster2.png | Bin
.../images/math-expressions/2Dcentroids.png | Bin
.../images/math-expressions/2Dcluster.png | Bin
.../query-guide}/images/math-expressions/add.png | Bin
.../query-guide}/images/math-expressions/aggs.png | Bin
.../images/math-expressions/anomaly.png | Bin
.../query-guide}/images/math-expressions/array.png | Bin
.../images/math-expressions/autocorr.png | Bin
.../query-guide}/images/math-expressions/bar.png | Bin
.../query-guide}/images/math-expressions/beta.png | Bin
.../images/math-expressions/binomial.png | Bin
.../images/math-expressions/bivariate.png | Bin
.../images/math-expressions/cartesian.png | Bin
.../images/math-expressions/cartogram.png | Bin
.../images/math-expressions/centroidplot.png | Bin
.../images/math-expressions/centroidzoom.png | Bin
.../images/math-expressions/clusters.png | Bin
.../images/math-expressions/clusterzip.png | Bin
.../images/math-expressions/clusterzipplot.png | Bin
.../images/math-expressions/commit-series.png | Bin
.../images/math-expressions/constant.png | Bin
.../images/math-expressions/conv-smooth.png | Bin
.../query-guide}/images/math-expressions/conv1.png | Bin
.../query-guide}/images/math-expressions/conv2.png | Bin
.../query-guide}/images/math-expressions/conv3.png | Bin
.../query-guide}/images/math-expressions/conv4.png | Bin
.../images/math-expressions/convex.png | Bin
.../images/math-expressions/convex0.png | Bin
.../images/math-expressions/convex1.png | Bin
.../images/math-expressions/convex2.png | Bin
.../images/math-expressions/correlation.png | Bin
.../images/math-expressions/corrmatrix.png | Bin
.../images/math-expressions/corrmatrix2.png | Bin
.../images/math-expressions/corrsim1.png | Bin
.../images/math-expressions/corrsim2.png | Bin
.../images/math-expressions/corrsim3.png | Bin
.../images/math-expressions/covariance.png | Bin
.../images/math-expressions/crosscorr.png | Bin
.../query-guide}/images/math-expressions/csv.png | Bin
.../images/math-expressions/csvselect.png | Bin
.../images/math-expressions/csvtable.png | Bin
.../images/math-expressions/cumPct.png | Bin
.../images/math-expressions/cumProb.png | Bin
.../images/math-expressions/curve-fitting.png | Bin
.../images/math-expressions/custom-hist.png | Bin
.../images/math-expressions/dbscan1.png | Bin
.../images/math-expressions/dbscan2.png | Bin
.../query-guide}/images/math-expressions/delay.png | Bin
.../images/math-expressions/derivative.png | Bin
.../images/math-expressions/derivative1.png | Bin
.../images/math-expressions/derivative2.png | Bin
.../images/math-expressions/derivatives.png | Bin
.../images/math-expressions/describe.png | Bin
.../images/math-expressions/diagnostics.png | Bin
.../query-guide}/images/math-expressions/diff.png | Bin
.../query-guide}/images/math-expressions/diff1.png | Bin
.../images/math-expressions/diffcorr.png | Bin
.../images/math-expressions/diffzoom.png | Bin
.../query-guide}/images/math-expressions/dist.png | Bin
.../images/math-expressions/distance.png | Bin
.../images/math-expressions/distanceview.png | Bin
.../images/math-expressions/empirical.png | Bin
.../query-guide}/images/math-expressions/enum1.png | Bin
.../query-guide}/images/math-expressions/enum2.png | Bin
.../images/math-expressions/expmoving.png | Bin
.../images/math-expressions/facet2D.png | Bin
.../images/math-expressions/facettab1.png | Bin
.../images/math-expressions/facettab2.png | Bin
.../images/math-expressions/facetviz1.png | Bin
.../images/math-expressions/facetviz2.png | Bin
.../query-guide}/images/math-expressions/fft.png | Bin
.../images/math-expressions/forecast.png | Bin
.../images/math-expressions/freqTable.png | Bin
.../images/math-expressions/freqTable1.png | Bin
.../images/math-expressions/fuzzyk.png | Bin
.../query-guide}/images/math-expressions/gamma.png | Bin
.../images/math-expressions/gaussfit.png | Bin
.../images/math-expressions/gaussfit2.png | Bin
.../images/math-expressions/geometric.png | Bin
.../images/math-expressions/graph1.png | Bin
.../images/math-expressions/graph2.png | Bin
.../images/math-expressions/harmfit.png | Bin
.../images/math-expressions/harmfit2.png | Bin
.../images/math-expressions/hashRollup.png | Bin
.../images/math-expressions/having.png | Bin
.../images/math-expressions/having2.png | Bin
.../images/math-expressions/having3.png | Bin
.../images/math-expressions/havingId.png | Bin
.../images/math-expressions/havingIsNull.png | Bin
.../images/math-expressions/havingNotNull.png | Bin
.../query-guide}/images/math-expressions/heat.png | Bin
.../query-guide}/images/math-expressions/hfit.png | Bin
.../hidden-signal-autocorrelation.png | Bin
.../images/math-expressions/hidden-signal-fft.png | Bin
.../images/math-expressions/hidden-signal.png | Bin
.../query-guide}/images/math-expressions/hist.png | Bin
.../images/math-expressions/histtable.png | Bin
.../images/math-expressions/hullplot.png | Bin
.../images/math-expressions/ifIsNull.png | Bin
.../images/math-expressions/integral.png | Bin
.../images/math-expressions/interpolate1.png | Bin
.../query-guide}/images/math-expressions/knn.png | Bin
.../images/math-expressions/knnRegress.png | Bin
.../images/math-expressions/knnSearch.png | Bin
.../query-guide}/images/math-expressions/line.png | Bin
.../query-guide}/images/math-expressions/line1.png | Bin
.../images/math-expressions/linear.png | Bin
.../query-guide}/images/math-expressions/loess.png | Bin
.../images/math-expressions/lognormal.png | Bin
.../images/math-expressions/logs-collection.png | Bin
.../images/math-expressions/logs-dates.png | Bin
.../images/math-expressions/logs-sample.png | Bin
.../images/math-expressions/logs-time-series.png | Bin
.../images/math-expressions/logs-time-series2.png | Bin
.../images/math-expressions/logs-time-series3.png | Bin
.../math-expressions/logs-type-collection.png | Bin
.../images/math-expressions/logs-type.png | Bin
.../query-guide}/images/math-expressions/mad.png | Bin
.../images/math-expressions/maddist.png | Bin
.../images/math-expressions/madsort.png | Bin
.../query-guide}/images/math-expressions/map.png | Bin
.../images/math-expressions/matches.png | Bin
.../images/math-expressions/matrix.png | Bin
.../images/math-expressions/minmaxscale.png | Bin
.../query-guide}/images/math-expressions/mnorm.png | Bin
.../images/math-expressions/mnorm1.png | Bin
.../images/math-expressions/mnorm2.png | Bin
.../images/math-expressions/monte-carlo.png | Bin
.../images/math-expressions/movingMedian.png | Bin
.../images/math-expressions/movingavg.png | Bin
.../images/math-expressions/multitime1.png | Bin
.../images/math-expressions/nodestab.png | Bin
.../images/math-expressions/nodesviz.png | Bin
.../math-expressions/noise-autocorrelation.png | Bin
.../images/math-expressions/noise-fft.png | Bin
.../query-guide}/images/math-expressions/noise.png | Bin
.../query-guide}/images/math-expressions/num.png | Bin
.../images/math-expressions/number.png | Bin
.../images/math-expressions/outliers.png | Bin
.../images/math-expressions/overlay-series.png | Bin
.../images/math-expressions/paging.png | Bin
.../images/math-expressions/poisson.png | Bin
.../images/math-expressions/polyfit-predict.png | Bin
.../images/math-expressions/polyfit-resid.png | Bin
.../images/math-expressions/polyfit.png | Bin
.../images/math-expressions/qtime-dist.png | Bin
.../math-expressions/qtime-highest-scatter.png | Bin
.../images/math-expressions/qtime-scatter.png | Bin
.../images/math-expressions/qtime-series.png | Bin
.../images/math-expressions/quantile-plot.png | Bin
.../images/math-expressions/quantiles.png | Bin
.../images/math-expressions/quantiles1.png | Bin
.../images/math-expressions/query-ids.png | Bin
.../images/math-expressions/query-qq.png | Bin
.../images/math-expressions/query-shard-level.png | Bin
.../images/math-expressions/query-spike.png | Bin
.../images/math-expressions/query-top-level.png | Bin
.../images/math-expressions/randomwalk1.png | Bin
.../images/math-expressions/randomwalk2.png | Bin
.../images/math-expressions/randomwalk3.png | Bin
.../images/math-expressions/randomwalk4.png | Bin
.../images/math-expressions/randomwalk5.1.png | Bin
.../images/math-expressions/randomwalk5.png | Bin
.../images/math-expressions/randomwalk6.png | Bin
.../images/math-expressions/ratscatter.png | Bin
.../images/math-expressions/recNum.png | Bin
.../images/math-expressions/redwine1.png | Bin
.../images/math-expressions/redwine2.png | Bin
.../images/math-expressions/regression-plot.png | Bin
.../images/math-expressions/residual-plot.png | Bin
.../images/math-expressions/residual-plot2.png | Bin
.../images/math-expressions/residuals.png | Bin
.../images/math-expressions/sample-overlay.png | Bin
.../images/math-expressions/sample-scatter.png | Bin
.../images/math-expressions/sample-scatter1.png | Bin
.../images/math-expressions/scalar.png | Bin
.../images/math-expressions/scoring.png | Bin
.../images/math-expressions/search-error.png | Bin
.../images/math-expressions/search-matches.png | Bin
.../images/math-expressions/search-page.png | Bin
.../images/math-expressions/search-resort.png | Bin
.../images/math-expressions/search-sort-plot.png | Bin
.../images/math-expressions/search-sort.png | Bin
.../images/math-expressions/search.png | Bin
.../images/math-expressions/search1.png | Bin
.../images/math-expressions/searchiris.png | Bin
.../images/math-expressions/season.png | Bin
.../images/math-expressions/seasondiff.png | Bin
.../images/math-expressions/select-math.png | Bin
.../images/math-expressions/select1.png | Bin
.../images/math-expressions/select2.png | Bin
.../images/math-expressions/selectconcat.png | Bin
.../images/math-expressions/selectupper.png | Bin
.../images/math-expressions/selectuuid.png | Bin
.../math-expressions/signal-autocorrelation.png | Bin
.../images/math-expressions/signal-fft.png | Bin
.../images/math-expressions/signal.png | Bin
.../images/math-expressions/significantTerms2.png | Bin
.../math-expressions/significantTermsCompare.png | Bin
.../query-guide}/images/math-expressions/sined.png | Bin
.../images/math-expressions/sinewave.png | Bin
.../images/math-expressions/sinewave256.png | Bin
.../images/math-expressions/skipping.png | Bin
.../images/math-expressions/slow-nodes.png | Bin
.../images/math-expressions/slow-queries.png | Bin
.../images/math-expressions/spline.png | Bin
.../images/math-expressions/sqlagg.png | Bin
.../query-guide}/images/math-expressions/stack.png | Bin
.../images/math-expressions/standardize.png | Bin
.../images/math-expressions/stats-table.png | Bin
.../query-guide}/images/math-expressions/stats.png | Bin
.../images/math-expressions/sterms.png | Bin
.../images/math-expressions/stream.png | Bin
.../images/math-expressions/striding.png | Bin
.../query-guide}/images/math-expressions/table.png | Bin
.../images/math-expressions/text-analytics.png | Bin
.../images/math-expressions/timecompare.png | Bin
.../images/math-expressions/timemodel.png | Bin
.../images/math-expressions/timeseries.png | Bin
.../images/math-expressions/timeseries1.png | Bin
.../images/math-expressions/timeseries2.png | Bin
.../query-guide}/images/math-expressions/trend.png | Bin
.../images/math-expressions/triangular.png | Bin
.../images/math-expressions/uniform.png | Bin
.../images/math-expressions/uniformr.png | Bin
.../images/math-expressions/unitize.png | Bin
.../images/math-expressions/univariate.png | Bin
.../images/math-expressions/update.png | Bin
.../images/math-expressions/valueat.png | Bin
.../images/math-expressions/variables.png | Bin
.../images/math-expressions/variables1.png | Bin
.../images/math-expressions/vector.png | Bin
.../images/math-expressions/weibull.png | Bin
.../query-guide}/images/math-expressions/xy.png | Bin
.../images/math-expressions/xyscatter.png | Bin
.../images/math-expressions/zepconf.png | Bin
.../query-guide}/images/math-expressions/zipf.png | Bin
.../images/other-parsers/graph_qparser_example.png | Bin
.../images/other-parsers/graph_qparser_example.svg | 0
.../query-guide}/images/query-screen/query-top.png | Bin
.../result-clustering/carrot2-docs-attrs1.png | Bin
.../result-clustering/carrot2-docs-attrs2.png | Bin
.../images/result-clustering/carrot2.png | Bin
.../query-guide}/images/spatial-search/bbox.png | Bin
.../query-guide}/images/spatial-search/circle.png | Bin
.../query-guide/images/sql-query/cluster.png | Bin 0 -> 3067133 bytes
.../images/sql-screen/sql-query-ui.png | Bin
.../images/stream-screen/StreamScreen.png | Bin
.../pages/analytics-expression-sources.adoc | 93 +
.../pages/analytics-mapping-functions.adoc | 361 ++
.../pages/analytics-reduction-functions.adoc | 126 +
.../modules/query-guide/pages/analytics.adoc | 967 +++++
.../query-guide/pages/block-join-query-parser.adoc | 213 ++
.../pages/collapse-and-expand-results.adoc | 315 ++
.../query-guide/pages/common-query-parameters.adoc | 480 +++
.../query-guide/pages/computational-geometry.adoc | 158 +
.../modules/query-guide/pages/curve-fitting.adoc | 116 +
.../query-guide/pages/dense-vector-search.adoc | 314 ++
.../query-guide/pages/dismax-query-parser.adoc | 265 ++
.../query-guide/pages/document-transformers.adoc | 419 +++
.../modules/query-guide/pages/dsp.adoc | 264 ++
.../query-guide/pages/edismax-query-parser.adoc | 253 ++
.../query-guide/pages/exporting-result-sets.adoc | 107 +
.../modules/query-guide/pages/faceting.adoc | 880 +++++
.../query-guide/pages/function-queries.adoc | 612 ++++
.../modules/query-guide/pages/graph-traversal.adoc | 646 ++++
.../modules/query-guide/pages/graph.adoc | 770 ++++
.../modules/query-guide/pages/highlighting.adoc | 761 ++++
.../query-guide/pages/jdbc-dbvisualizer.adoc | 125 +
.../query-guide/pages}/jdbc-python-jython.adoc | 0
.../{src => modules/query-guide/pages}/jdbc-r.adoc | 0
.../modules/query-guide/pages/jdbc-squirrel.adoc | 101 +
.../modules/query-guide/pages/jdbc-zeppelin.adoc | 91 +
.../query-guide/pages/join-query-parser.adoc | 342 ++
.../modules/query-guide/pages/json-facet-api.adoc | 1073 ++++++
.../pages/json-faceting-domain-changes.adoc | 308 ++
.../modules/query-guide/pages/json-query-dsl.adoc | 508 +++
.../query-guide/pages/json-request-api.adoc | 296 ++
.../query-guide/pages/learning-to-rank.adoc | 900 +++++
.../modules/query-guide/pages/loading.adoc | 528 +++
.../modules/query-guide/pages/local-params.adoc | 89 +
.../modules/query-guide/pages/logs.adoc | 364 ++
.../query-guide/pages/machine-learning.adoc | 752 ++++
.../query-guide/pages/math-expressions.adoc | 50 +
.../modules/query-guide/pages/math-start.adoc | 118 +
.../modules/query-guide/pages/matrix-math.adoc | 457 +++
.../modules/query-guide/pages/morelikethis.adoc | 646 ++++
.../query-guide/pages/numerical-analysis.adoc | 257 ++
.../modules/query-guide/pages/other-parsers.adoc | 1441 ++++++++
.../query-guide/pages/pagination-of-results.adoc | 291 ++
.../pages/probability-distributions.adoc | 384 ++
.../pages/query-elevation-component.adoc | 238 ++
.../query-guide/pages/query-re-ranking.adoc | 91 +
.../modules/query-guide/pages/query-screen.adoc | 101 +
.../pages/query-syntax-and-parsers.adoc | 72 +
.../modules/query-guide/pages/regression.adoc | 455 +++
.../query-guide/pages/response-writers.adoc | 417 +++
.../query-guide/pages/result-clustering.adoc | 591 +++
.../modules/query-guide/pages/result-grouping.adoc | 390 ++
.../modules/query-guide/pages/scalar-math.adoc | 151 +
.../modules/query-guide/pages/search-sample.adoc | 253 ++
.../pages/searching-nested-documents.adoc | 298 ++
.../modules/query-guide/pages/simulations.adoc | 221 ++
.../modules/query-guide/pages/spatial-search.adoc | 733 ++++
.../modules/query-guide/pages/spell-checking.adoc | 528 +++
.../modules/query-guide/pages/sql-query.adoc | 569 +++
.../modules/query-guide/pages/sql-screen.adoc | 26 +
.../query-guide/pages/standard-query-parser.adoc | 451 +++
.../modules/query-guide/pages/statistics.adoc | 731 ++++
.../modules/query-guide/pages/stats-component.adoc | 230 ++
.../modules/query-guide/pages/stream-api.adoc | 211 ++
.../pages/stream-decorator-reference.adoc | 1486 ++++++++
.../pages/stream-evaluator-reference.adoc | 2487 +++++++++++++
.../modules/query-guide/pages/stream-screen.adoc | 31 +
.../query-guide/pages/stream-source-reference.adoc | 756 ++++
.../query-guide/pages/streaming-expressions.adoc | 145 +
.../modules/query-guide/pages/suggester.adoc | 937 +++++
.../modules/query-guide/pages/tagger-handler.adoc | 351 ++
.../query-guide/pages/term-vector-component.adoc | 238 ++
.../modules/query-guide/pages/term-vectors.adoc | 285 ++
.../modules/query-guide/pages/terms-component.adoc | 472 +++
.../modules/query-guide/pages/time-series.adoc | 286 ++
.../modules/query-guide/pages/transform.adoc | 113 +
.../modules/query-guide/pages/variables.adoc | 364 ++
.../modules/query-guide/pages/vector-math.adoc | 622 ++++
.../modules/query-guide/pages/visualization.adoc | 146 +
.../modules/query-guide/querying-nav.adoc | 85 +
.../pages/major-changes-in-solr-6.adoc | 102 +
.../pages/major-changes-in-solr-7.adoc | 254 ++
.../pages/major-changes-in-solr-8.adoc | 509 +++
.../pages/major-changes-in-solr-9.adoc | 312 ++
.../upgrade-notes/pages/solr-upgrade-notes.adoc | 860 +++++
.../modules/upgrade-notes/upgrade-nav.adoc | 5 +
solr/solr-ref-guide/playbook.template.yml | 40 +
solr/solr-ref-guide/src/.gitignore | 3 -
solr/solr-ref-guide/src/_config.yml.template | 100 -
solr/solr-ref-guide/src/_data/strings.yml | 5 -
solr/solr-ref-guide/src/_data/tags.yml | 7 -
solr/solr-ref-guide/src/_includes/footer.html | 9 -
solr/solr-ref-guide/src/_includes/head.html | 32 -
.../src/_includes/mathjax-support.html | 22 -
solr/solr-ref-guide/src/_includes/sidebar.html | 90 -
solr/solr-ref-guide/src/_includes/topnav.html | 39 -
solr/solr-ref-guide/src/_layouts/default.html | 63 -
solr/solr-ref-guide/src/_layouts/home.html | 21 -
solr/solr-ref-guide/src/_layouts/none.html | 3 -
solr/solr-ref-guide/src/_layouts/page.html | 57 -
.../src/_templates/_attribution.html.slim | 4 -
.../src/_templates/_footer.html.slim | 8 -
.../src/_templates/_footnotes.html.slim | 11 -
.../src/_templates/_hdlist.html.slim | 20 -
.../src/_templates/_header.html.slim | 27 -
.../solr-ref-guide/src/_templates/_qanda.html.slim | 12 -
solr/solr-ref-guide/src/_templates/_toc.html.slim | 4 -
.../solr-ref-guide/src/_templates/colist.html.slim | 8 -
solr/solr-ref-guide/src/_templates/dlist.html.slim | 13 -
.../src/_templates/document.html.slim | 30 -
solr/solr-ref-guide/src/_templates/helpers.rb | 670 ----
solr/solr-ref-guide/src/_templates/image.html.slim | 3 -
.../src/_templates/inline_anchor.html.slim | 12 -
.../src/_templates/inline_break.html.slim | 2 -
.../src/_templates/inline_button.html.slim | 1 -
.../src/_templates/inline_callout.html.slim | 1 -
.../src/_templates/inline_footnote.html.slim | 9 -
.../src/_templates/inline_image.html.slim | 10 -
.../src/_templates/inline_indexterm.html.slim | 2 -
.../src/_templates/inline_kbd.html.slim | 7 -
.../src/_templates/inline_menu.html.slim | 15 -
.../src/_templates/inline_quoted.html.slim | 29 -
.../src/_templates/listing.html.slim | 15 -
.../src/_templates/literal.html.slim | 2 -
solr/solr-ref-guide/src/_templates/olist.html.slim | 4 -
solr/solr-ref-guide/src/_templates/open.html.slim | 7 -
.../src/_templates/paragraph.html.slim | 6 -
.../src/_templates/preamble.html.slim | 4 -
solr/solr-ref-guide/src/_templates/quote.html.slim | 6 -
.../src/_templates/sidebar.html.slim | 4 -
solr/solr-ref-guide/src/_templates/table.html.slim | 39 -
solr/solr-ref-guide/src/_templates/toc.html.slim | 11 -
solr/solr-ref-guide/src/_templates/ulist.html.slim | 11 -
solr/solr-ref-guide/src/about-this-guide.adoc | 94 -
solr/solr-ref-guide/src/alias-management.adoc | 746 ----
solr/solr-ref-guide/src/aliases.adoc | 359 --
solr/solr-ref-guide/src/analysis-screen.adoc | 71 -
.../src/analytics-expression-sources.adoc | 93 -
.../src/analytics-mapping-functions.adoc | 361 --
.../src/analytics-reduction-functions.adoc | 126 -
solr/solr-ref-guide/src/analytics.adoc | 967 -----
solr/solr-ref-guide/src/analyzers.adoc | 186 -
.../authentication-and-authorization-plugins.adoc | 224 --
solr/solr-ref-guide/src/backup-restore.adoc | 791 ----
.../src/basic-authentication-plugin.adoc | 364 --
.../src/block-join-query-parser.adoc | 213 --
solr/solr-ref-guide/src/caches-warming.adoc | 343 --
.../src/cert-authentication-plugin.adoc | 61 -
solr/solr-ref-guide/src/client-apis.adoc | 73 -
solr/solr-ref-guide/src/cloud-screens.adoc | 67 -
.../src/cluster-node-management.adoc | 876 -----
solr/solr-ref-guide/src/codec-factory.adoc | 58 -
.../src/collapse-and-expand-results.adoc | 315 --
solr/solr-ref-guide/src/collection-management.adoc | 2191 ------------
solr/solr-ref-guide/src/collections-api.adoc | 303 --
.../solr-ref-guide/src/collections-core-admin.adoc | 40 -
.../src/commits-transaction-logs.adoc | 322 --
.../src/common-query-parameters.adoc | 480 ---
.../solr-ref-guide/src/computational-geometry.adoc | 158 -
solr/solr-ref-guide/src/config-api.adoc | 933 -----
solr/solr-ref-guide/src/config-sets.adoc | 102 -
solr/solr-ref-guide/src/configsets-api.adoc | 386 --
solr/solr-ref-guide/src/configuration-files.adoc | 107 -
solr/solr-ref-guide/src/configuring-logging.adoc | 159 -
solr/solr-ref-guide/src/configuring-solr-xml.adoc | 593 ---
.../src/configuring-solrconfig-xml.adoc | 74 -
solr/solr-ref-guide/src/content-streams.adoc | 94 -
solr/solr-ref-guide/src/copy-fields.adoc | 67 -
solr/solr-ref-guide/src/core-discovery.adoc | 219 --
solr/solr-ref-guide/src/coreadmin-api.adoc | 728 ----
solr/solr-ref-guide/src/css/decoration.css | 288 --
solr/solr-ref-guide/src/css/navs.css | 366 --
solr/solr-ref-guide/src/css/ref-guide.css | 2378 -------------
solr/solr-ref-guide/src/css/search.css | 47 -
.../src/currencies-exchange-rates.adoc | 142 -
solr/solr-ref-guide/src/curve-fitting.adoc | 116 -
solr/solr-ref-guide/src/de-duplication.adoc | 131 -
solr/solr-ref-guide/src/dense-vector-search.adoc | 314 --
solr/solr-ref-guide/src/dismax-query-parser.adoc | 265 --
solr/solr-ref-guide/src/distributed-tracing.adoc | 79 -
solr/solr-ref-guide/src/docker-faq.adoc | 346 --
solr/solr-ref-guide/src/document-analysis.adoc | 65 -
solr/solr-ref-guide/src/document-transformers.adoc | 419 ---
.../src/documents-fields-schema-design.adoc | 101 -
solr/solr-ref-guide/src/documents-screen.adoc | 86 -
solr/solr-ref-guide/src/docvalues.adoc | 118 -
solr/solr-ref-guide/src/dsp.adoc | 264 --
solr/solr-ref-guide/src/edismax-query-parser.adoc | 253 --
solr/solr-ref-guide/src/enabling-ssl.adoc | 446 ---
solr/solr-ref-guide/src/exporting-result-sets.adoc | 107 -
.../src/external-files-processes.adoc | 318 --
solr/solr-ref-guide/src/faceting.adoc | 880 -----
.../src/field-properties-by-use-case.adoc | 56 -
.../src/field-type-definitions-and-properties.adoc | 258 --
.../src/field-types-included-with-solr.adoc | 114 -
solr/solr-ref-guide/src/fields.adoc | 76 -
solr/solr-ref-guide/src/filters.adoc | 3761 --------------------
.../src/fonts/fontawesome/FontAwesome.otf | Bin 85908 -> 0 bytes
.../src/fonts/fontawesome/fontawesome-webfont.eot | Bin 56006 -> 0 bytes
.../src/fonts/fontawesome/fontawesome-webfont.svg | 520 ---
.../src/fonts/fontawesome/fontawesome-webfont.ttf | Bin 112160 -> 0 bytes
.../src/fonts/fontawesome/fontawesome-webfont.woff | Bin 65452 -> 0 bytes
solr/solr-ref-guide/src/function-queries.adoc | 611 ----
solr/solr-ref-guide/src/graph-traversal.adoc | 646 ----
solr/solr-ref-guide/src/graph.adoc | 770 ----
.../src/hadoop-authentication-plugin.adoc | 223 --
solr/solr-ref-guide/src/highlighting.adoc | 761 ----
.../src/implicit-requesthandlers.adoc | 387 --
solr/solr-ref-guide/src/index-location-format.adoc | 65 -
.../solr-ref-guide/src/index-segments-merging.adoc | 380 --
solr/solr-ref-guide/src/index.adoc | 61 -
.../src/indexing-nested-documents.adoc | 543 ---
solr/solr-ref-guide/src/indexing-with-tika.adoc | 632 ----
.../src/indexing-with-update-handlers.adoc | 760 ----
solr/solr-ref-guide/src/initparams.adoc | 137 -
solr/solr-ref-guide/src/installing-solr.adoc | 227 --
solr/solr-ref-guide/src/introduction.adoc | 43 -
solr/solr-ref-guide/src/javascript.adoc | 30 -
solr/solr-ref-guide/src/jdbc-dbvisualizer.adoc | 125 -
solr/solr-ref-guide/src/jdbc-squirrel.adoc | 101 -
solr/solr-ref-guide/src/jdbc-zeppelin.adoc | 91 -
solr/solr-ref-guide/src/jmx-with-solr.adoc | 78 -
solr/solr-ref-guide/src/join-query-parser.adoc | 342 --
solr/solr-ref-guide/src/js/customscripts.js | 79 -
solr/solr-ref-guide/src/js/jekyll-search.js | 1 -
solr/solr-ref-guide/src/js/jquery.navgoco.min.js | 8 -
solr/solr-ref-guide/src/json-facet-api.adoc | 1075 ------
.../src/json-faceting-domain-changes.adoc | 310 --
solr/solr-ref-guide/src/json-query-dsl.adoc | 510 ---
solr/solr-ref-guide/src/json-request-api.adoc | 299 --
solr/solr-ref-guide/src/jvm-settings.adoc | 84 -
.../src/jwt-authentication-plugin.adoc | 274 --
.../src/kerberos-authentication-plugin.adoc | 547 ---
solr/solr-ref-guide/src/language-analysis.adoc | 3430 ------------------
solr/solr-ref-guide/src/language-detection.adoc | 296 --
solr/solr-ref-guide/src/learning-to-rank.adoc | 900 -----
solr/solr-ref-guide/src/libs.adoc | 75 -
solr/solr-ref-guide/src/loading.adoc | 528 ---
solr/solr-ref-guide/src/local-params.adoc | 89 -
solr/solr-ref-guide/src/logs.adoc | 364 --
solr/solr-ref-guide/src/luke-request-handler.adoc | 120 -
solr/solr-ref-guide/src/machine-learning.adoc | 752 ----
.../src/major-changes-in-solr-6.adoc | 90 -
.../src/major-changes-in-solr-7.adoc | 202 --
.../src/major-changes-in-solr-8.adoc | 510 ---
.../src/major-changes-in-solr-9.adoc | 312 --
solr/solr-ref-guide/src/managed-resources.adoc | 314 --
solr/solr-ref-guide/src/math-expressions.adoc | 90 -
solr/solr-ref-guide/src/math-start.adoc | 118 -
solr/solr-ref-guide/src/matrix-math.adoc | 457 ---
solr/solr-ref-guide/src/mbean-request-handler.adoc | 84 -
solr/solr-ref-guide/src/metrics-reporting.adoc | 876 -----
.../monitoring-with-prometheus-and-grafana.adoc | 570 ---
solr/solr-ref-guide/src/morelikethis.adoc | 646 ----
solr/solr-ref-guide/src/numerical-analysis.adoc | 257 --
.../src/{ => old-pages}/configuration-apis.adoc | 0
.../src/{ => old-pages}/configuration-guide.adoc | 0
.../src/{ => old-pages}/controlling-results.adoc | 0
.../src/{ => old-pages}/deployment-guide.adoc | 0
.../src/{ => old-pages}/enhancing-queries.adoc | 0
.../src/{ => old-pages}/field-types.adoc | 0
.../{ => old-pages}/fields-and-schema-design.adoc | 0
.../src/{ => old-pages}/getting-started.adoc | 0
.../{ => old-pages}/indexing-data-operations.adoc | 0
.../{ => old-pages}/installation-deployment.adoc | 0
.../src/{ => old-pages}/monitoring-solr.adoc | 0
.../src/{ => old-pages}/query-guide.adoc | 0
.../src/{ => old-pages}/scaling-solr.adoc | 0
.../src/{ => old-pages}/schema-indexing-guide.adoc | 0
.../src/{ => old-pages}/solr-concepts.adoc | 0
.../src/{ => old-pages}/solr-schema.adoc | 0
.../src/{ => old-pages}/solrcloud-clusters.adoc | 0
.../src/{ => old-pages}/user-managed-clusters.adoc | 0
solr/solr-ref-guide/src/other-parsers.adoc | 1441 --------
solr/solr-ref-guide/src/package-manager.adoc | 210 --
solr/solr-ref-guide/src/pagination-of-results.adoc | 291 --
.../src/partial-document-updates.adoc | 545 ---
.../src/performance-statistics-reference.adoc | 222 --
solr/solr-ref-guide/src/phonetic-matching.adoc | 139 -
solr/solr-ref-guide/src/ping.adoc | 92 -
solr/solr-ref-guide/src/plugins-stats-screen.adoc | 30 -
solr/solr-ref-guide/src/post-tool.adoc | 190 -
.../src/probability-distributions.adoc | 384 --
solr/solr-ref-guide/src/property-substitution.adoc | 146 -
solr/solr-ref-guide/src/python.adoc | 71 -
.../src/query-elevation-component.adoc | 238 --
solr/solr-ref-guide/src/query-re-ranking.adoc | 91 -
solr/solr-ref-guide/src/query-screen.adoc | 101 -
.../src/query-syntax-and-parsers.adoc | 71 -
solr/solr-ref-guide/src/realtime-get.adoc | 222 --
solr/solr-ref-guide/src/regression.adoc | 455 ---
solr/solr-ref-guide/src/reindexing.adoc | 174 -
solr/solr-ref-guide/src/replica-management.adoc | 809 -----
.../solr-ref-guide/src/request-parameters-api.adoc | 230 --
solr/solr-ref-guide/src/requestdispatcher.adoc | 212 --
.../src/requesthandlers-searchcomponents.adoc | 332 --
solr/solr-ref-guide/src/resource-loading.adoc | 46 -
solr/solr-ref-guide/src/response-writers.adoc | 417 ---
solr/solr-ref-guide/src/result-clustering.adoc | 591 ---
solr/solr-ref-guide/src/result-grouping.adoc | 390 --
solr/solr-ref-guide/src/ruby.adoc | 115 -
.../src/rule-based-authorization-plugin.adoc | 583 ---
solr/solr-ref-guide/src/scalar-math.adoc | 151 -
solr/solr-ref-guide/src/schema-api.adoc | 1654 ---------
solr/solr-ref-guide/src/schema-browser-screen.adoc | 49 -
solr/solr-ref-guide/src/schema-designer.adoc | 236 --
solr/solr-ref-guide/src/schema-elements.adoc | 158 -
solr/solr-ref-guide/src/schema-factory.adoc | 133 -
solr/solr-ref-guide/src/schemaless-mode.adoc | 339 --
.../src/script-update-processor.adoc | 297 --
solr/solr-ref-guide/src/search-sample.adoc | 253 --
solr/solr-ref-guide/src/search.json | 21 -
solr/solr-ref-guide/src/searching-in-solr.adoc | 89 -
.../src/searching-nested-documents.adoc | 297 --
solr/solr-ref-guide/src/securing-solr.adoc | 118 -
solr/solr-ref-guide/src/security-ui.adoc | 110 -
solr/solr-ref-guide/src/shard-management.adoc | 626 ----
solr/solr-ref-guide/src/simulations.adoc | 221 --
solr/solr-ref-guide/src/sitemap.xml | 17 -
solr/solr-ref-guide/src/solr-admin-ui.adoc | 191 -
.../src/solr-control-script-reference.adoc | 1478 --------
solr/solr-ref-guide/src/solr-glossary.adoc | 240 --
solr/solr-ref-guide/src/solr-in-docker.adoc | 349 --
solr/solr-ref-guide/src/solr-indexing.adoc | 59 -
solr/solr-ref-guide/src/solr-modules.adoc | 41 -
solr/solr-ref-guide/src/solr-on-hdfs.adoc | 288 --
solr/solr-ref-guide/src/solr-plugins.adoc | 67 -
solr/solr-ref-guide/src/solr-tutorial.adoc | 99 -
solr/solr-ref-guide/src/solr-upgrade-notes.adoc | 865 -----
.../src/solrcloud-distributed-requests.adoc | 462 ---
.../src/solrcloud-shards-indexing.adoc | 222 --
.../solrcloud-with-legacy-configuration-files.adoc | 77 -
solr/solr-ref-guide/src/solrj.adoc | 262 --
solr/solr-ref-guide/src/spatial-search.adoc | 733 ----
solr/solr-ref-guide/src/spell-checking.adoc | 528 ---
solr/solr-ref-guide/src/sql-query.adoc | 568 ---
solr/solr-ref-guide/src/sql-screen.adoc | 26 -
solr/solr-ref-guide/src/standard-query-parser.adoc | 450 ---
solr/solr-ref-guide/src/statistics.adoc | 731 ----
solr/solr-ref-guide/src/stats-component.adoc | 230 --
solr/solr-ref-guide/src/stream-api.adoc | 211 --
.../src/stream-decorator-reference.adoc | 1486 --------
.../src/stream-evaluator-reference.adoc | 2487 -------------
solr/solr-ref-guide/src/stream-screen.adoc | 31 -
.../src/stream-source-reference.adoc | 756 ----
solr/solr-ref-guide/src/streaming-expressions.adoc | 145 -
solr/solr-ref-guide/src/suggester.adoc | 937 -----
solr/solr-ref-guide/src/tagger-handler.adoc | 351 --
.../src/taking-solr-to-production.adoc | 477 ---
solr/solr-ref-guide/src/term-vector-component.adoc | 238 --
solr/solr-ref-guide/src/term-vectors.adoc | 285 --
solr/solr-ref-guide/src/terms-component.adoc | 472 ---
solr/solr-ref-guide/src/thread-dump.adoc | 47 -
solr/solr-ref-guide/src/time-series.adoc | 286 --
solr/solr-ref-guide/src/tokenizers.adoc | 916 -----
solr/solr-ref-guide/src/transform.adoc | 113 -
.../src/transforming-and-indexing-custom-json.adoc | 927 -----
solr/solr-ref-guide/src/tutorial-aws.adoc | 305 --
solr/solr-ref-guide/src/tutorial-diy.adoc | 110 -
solr/solr-ref-guide/src/tutorial-films.adoc | 462 ---
solr/solr-ref-guide/src/tutorial-solrcloud.adoc | 217 --
solr/solr-ref-guide/src/tutorial-techproducts.adoc | 509 ---
.../src/update-request-processors.adoc | 494 ---
.../src/upgrading-a-solr-cluster.adoc | 110 -
.../src/user-managed-distributed-search.adoc | 124 -
.../src/user-managed-index-replication.adoc | 524 ---
solr/solr-ref-guide/src/variables.adoc | 364 --
solr/solr-ref-guide/src/vector-math.adoc | 622 ----
solr/solr-ref-guide/src/visualization.adoc | 146 -
.../src/zookeeper-access-control.adoc | 241 --
solr/solr-ref-guide/src/zookeeper-ensemble.adoc | 552 ---
.../src/zookeeper-file-management.adoc | 100 -
solr/solr-ref-guide/src/zookeeper-utilities.adoc | 164 -
.../org/apache/solr/guide/BuildNavDataFiles.java | 298 --
.../apache/solr/guide/CheckLinksAndAnchors.java | 411 ---
solr/solr-ref-guide/ui-src/css/base.css | 123 +
solr/solr-ref-guide/ui-src/css/doc.css | 996 ++++++
solr/solr-ref-guide/ui-src/css/footer.css | 20 +
solr/solr-ref-guide/ui-src/css/header.css | 313 ++
solr/solr-ref-guide/ui-src/css/main.css | 37 +
solr/solr-ref-guide/ui-src/css/nav.css | 266 ++
solr/solr-ref-guide/ui-src/css/print.css | 86 +
solr/solr-ref-guide/ui-src/css/site.css | 19 +
solr/solr-ref-guide/ui-src/css/toc.css | 105 +
.../ui-src/css/typeface-inconsolata.css | 12 +
.../ui-src/css/typeface-noto-sans.css | 19 +
solr/solr-ref-guide/ui-src/css/vars.css | 160 +
.../font}/Inconsolata-Bold.ttf | Bin
.../font}/Inconsolata-Regular.ttf | Bin
.../{src/fonts => ui-src/font}/Inconsolata/OFL.txt | 0
.../Noto_Sans => ui-src/font}/NotoSans-Bold.ttf | Bin
.../font}/NotoSans-BoldItalic.ttf | Bin
.../Noto_Sans => ui-src/font}/NotoSans-Italic.ttf | Bin
.../Noto_Sans => ui-src/font}/NotoSans-Regular.ttf | Bin
.../fonts => ui-src/font}/Noto_Sans/LICENSE.txt | 0
.../{src/images/icons => ui-src/img}/favicon.ico | Bin
.../images => ui-src/img}/solr-sunOnly-small.png | Bin
solr/solr-ref-guide/ui-src/js/02-on-this-page.js | 118 +
.../ui-src/partials/footer-content.hbs | 5 +
solr/solr-ref-guide/ui-src/partials/head-icons.hbs | 3 +
.../ui-src/partials/header-content.hbs | 44 +
.../solr-ref-guide/ui-src/partials/nav-explore.hbs | 97 +
solr/solr-ref-guide/ui-src/partials/nav.hbs | 10 +
solr/solr-ref-guide/ui-src/partials/toc.hbs | 5 +
versions.lock | 25 +-
versions.props | 4 +-
939 files changed, 83352 insertions(+), 86460 deletions(-)
diff --git a/dev-docs/ref-guide/antora.adoc b/dev-docs/ref-guide/antora.adoc
new file mode 100644
index 0000000..2f3306f
--- /dev/null
+++ b/dev-docs/ref-guide/antora.adoc
@@ -0,0 +1,70 @@
+= Working with HTML Templates
+:toc:
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Solr Ref Guide uses Antora to build the HTML version of the site.
+
+== What is Antora?
+
+Antora is a static site generator, meaning that it takes some set of documents and produces HTML pages.
+It allows for templating of the pages, so each page has the same look and feel without having to code headers, footers, logos, etc., into every page.
+
+Antora is an open source project, online at https://antora.org/.
+
+== How We Use Antora
+
+The following sections describe the main features of Antora that you will encounter while working with the Solr Ref Guide.
+
+=== Asciidoctor
+Antora uses Asciidoctor.js by default as it's content markup language.
+
+Read more on the Solr xref:asciidoc-syntax.adoc[AsciiDoc Syntax] page, or on Antora's guide: https://docs.antora.org/antora/latest/asciidoc/asciidoc/
+
+=== playbook.yml
+
+The `playbook.yml` is a global configuration file that drives many of the options used when building the site.
+
+We have template-ized `playbook.template.yml`, instead of a hardcoded `playbook.yml`.
+Each gradle task that requires a `playbook.yml`, such as `gradlew buildLocalSite` or `gradlew buildOfficialSite`, will generate the `playbook.yml` that is needed based off of this template.
+
+It is unlikely that you will manually need to edit this very often.
+
+=== antora.yml
+
+The `antora.yml` is a configuration file for a specific version of a component in the Antora build.
+Therefore every version we release for the Solr ref-guide, or the Solr Operator ref-guide will have a separate `antora.yml`.
+
+This is also where version-specific variables are configured, such as dependency versions (lucene, zookeeper, etc.), Solr version, and javadocs location.
+
+The `antora.yml` that is used when building a local version of the site is not the version checked-into the repository.
+Instead a local `antora.yml` is built in the `build/` directory.
+The checked-in `antora.yml` is used when the official ref-guide is built.
+Antora will checkout all specified branches/tags and use the antora.yml to build the ref-guide for that branch's version.
+
+In order to test changes to the `antora.yml`, do not change this file directly.
+Instead, update `antora.template.yaml`, and `gradlew buildLocalSite` will build a site with the changes.
+
+The only reason you will likely need to change the `antora.template.yml` is if you are introducing new variables for dependency versions.
+
+== Building the HTML Site
+
+A Gradle target `gradlew buildLocalSite` will build the full HTML site (found in `solr/solr-ref-guide/build/site`).
+
+This target builds the navigation for the left-hand menu, and converts all `.adoc` files to `.html`, including navigation and inter-document links.
+
+The `checkSiteLinks` target also checks that all inter-doc and javadocs references are correct and resolvable.
diff --git a/dev-docs/ref-guide/asciidoc-syntax.adoc b/dev-docs/ref-guide/asciidoc-syntax.adoc
index 8031b2f..866ef85 100644
--- a/dev-docs/ref-guide/asciidoc-syntax.adoc
+++ b/dev-docs/ref-guide/asciidoc-syntax.adoc
@@ -17,7 +17,7 @@
// specific language governing permissions and limitations
// under the License.
-The definitive manual on AsciiDoc syntax is in the https://docs.asciidoctor.org/asciidoc/latest/[Asciidoctor documentation].
+The definitive manual on AsciiDoc syntax is in the https://docs.asciidoctor.org/asciidoctor.js/latest[Asciidoctor.js documentation].
To help people get started, however, here is a simpler cheat sheet.
== AsciiDoc vs Asciidoctor Syntax
@@ -109,49 +109,27 @@ When in doubt, choose `text`, or leave it blank.
The build system has the ability to "include" snippets located in other files -- even non-AsciiDoc files such as `*.java` source code files.
+These files must reside under the `examples/` directory in the same module as the page that wants to use it.
+
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 inserted into an `.adoc` file using an `include` directive, following the format: `include::PathToFileWithSnippet[tag=snippetName]`.
+Snippets can be inserted into an `.adoc` file using an `include` directive, following the format: `include::<directory-under-module>$<file-name>[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.
+Note that when paths are provided in these directives, those paths are resolved relative to the module that the AsciiDoc page lives in.
-Snippets can be included directly from any file in the Solr GIT repo by refering to a `solr-root-path` variable prior to the file path, for example:
+For example, `modules/deployment-guide/pages/solrj.adoc` uses the `UsingSolrJRefGuideExamplesTest.java` file located under `modules/deployment-guide/examples/`.
[source]
--
[source,java,indent=0]
----
-\include::{solr-root-path}core/src/java/org/apache/solr/core/SolrCore.java[tag=something]
+\include::example$UsingSolrJRefGuideExamplesTest.java[tag=solrj-solrclient-timeouts]
----
--
-When building the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `solr-ref-guide/build/content` directory used by Gradle.
-
-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.
-
-[source]
---
-= 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 https://docs.asciidoctor.org/asciidoc/latest/directives/include/.
+For more information on the `include` directive, see the documentation at https://docs.antora.org/antora/latest/page/include-an-example/.
=== Block Titles
@@ -185,10 +163,18 @@ There are slightly different rules depending on the type of link you want to cre
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:
+With all of the below examples, you can add text to display as the link title by putting the display text in brackets after the link, as in:
+
+[source]
+xref:indexing-guide:schema-api.adoc#modify-the-schema[Modify the Schema]
+
+You can also use the title of the Page or Section you are linking to by using an empty display text.
+This is useful in case the title of the page or section changes.
+In that case you won't need to change the display text for every link that refers to that page/section.
+See an example below:
[source]
-<<schema-api.adoc#modify-the-schema,Modify the Schema>>
+xref:indexing-guide:schema-api.adoc#modify-the-schema[]
==== Link to a Section on the Same Page
@@ -230,20 +216,32 @@ Take this example from `configsets-api.adoc`:
To link to this section, there are two approaches depending on where you are linking from:
* From the same page, simply use the anchor name: `\<<configsets-create>>`.
-* From another page, use the page name and the anchor name: `\<<configsets-api.adoc#configsets-create>>`.
+* From another page, use the page name and the anchor name: `\xref:configuration-guide:configsets-api.adoc#configsets-create[]`.
==== Link to Another Page
To link to _another page_ or a section on another page, you must refer to the full filename and refer to the section you want to link to.
-When you want to refer the reader to another page without deep-linking to a section, Asciidoctor allows a shorthand for this: you only need to specify an empty anchor (`#`) after the file name.
+When you want to refer the reader to another page without deep-linking to a section, Asciidoctor allows this by merely ommiting the `#` and section id.
Example::
-To construct a link to the `solr-upgrade-notes.adoc` page, we need to refer to the file name (`solr-upgrade-notes.adoc`), then use an empty anchor for the section reference.
+To construct a link to the `solr-upgrade-notes.adoc` page, we need to refer to the file name (`solr-upgrade-notes.adoc`), as well as the module that the file resides in (`upgrade-notes/`).
+You can determine the module that a page falls under by looking at the folder under `solr-ref-guide/modules` that it resides in.
++
It's preferred to also always use the page name to give the reader better context for where the link goes.
As in:
+
[source]
-For more about upgrades, see <<upgrading-solr.adoc#,Solr Upgrade Notes>>.
+For more about upgrades, see xref:upgrade-notes:solr-upgrade-notes.adoc[Solr Upgrade Notes].
+
+==== Link to Another Page in the same Module
+
+If the page that contains the link and the page being linked to reside in the same module, there is no need to include the module name after `xref:`
+
+Example::
+To construct a link to the `major-changes-in-solr-9.adoc` page from `solr-upgrade-notes.adoc` page, we do not need to include the module name because they both reside in the `upgrade-notes` module.
++
+[source]
+For more information on upgrading to Solr 9, see the section xref:major-changes-in-solr-9.adoc[].
==== Link to a Section on Another Page
Linking to a section is the same conceptually as linking to the top of a page, you just need to take a little extra care to format the anchor ID in your link reference properly.
@@ -280,7 +278,7 @@ To link from to this section from another page, you would create a link structur
The link in context would look like this:
+
[source]
-For more information, see the section <<schema-api.adoc#modify-the-schema,Modify the Schema>>.
+For more information, see the section xref:indexing-guide:schema-api.adoc#modify-the-schema[Modify the Schema].
More info: https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/
@@ -339,7 +337,11 @@ If a block image includes a title, it will be included as the text of the captio
Optional attributes allow you to set the alt text, the size of the image, if it should be a link, float and alignment.
-More info: https://docs.asciidoctor.org/asciidoc/latest/macros/images/
+Images must be placed in the `images/` directory under the module of the pages that wish to use that image.
+As you can see in the modules that exist now, the ref-guide generally includes sub-directories for each page in the module.
+This allows for better management of which pages are using which images.
+
+More info: https://docs.antora.org/antora/latest/page/images/
== Tables
diff --git a/dev-docs/ref-guide/jekyll.adoc b/dev-docs/ref-guide/jekyll.adoc
deleted file mode 100644
index a6b206d..0000000
--- a/dev-docs/ref-guide/jekyll.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-= Working with HTML Templates
-:toc:
-// 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
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-The Solr Ref Guide uses Jekyll to build the HTML version of the site.
-
-== What is Jekyll?
-
-Jekyll is a static site generator, meaning that it takes some set of documents and produces HTML pages. It allows for templating of the pages, so each page has the same look and feel without having to code headers, footers, logos, etc., into every page.
-
-Jekyll is an open source project written in Ruby, online at https://jekyllrb.com/.
-
-== How We Use Jekyll
-
-The following sections describe the main features of Jekyll that you will encounter while working with the Solr Ref Guide.
-
-=== 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 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:
-
-* `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.
-
-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`).
-
-==== Table of Contents
-There are some optional custom attributes that can be defined in pages to affect the Table of Contents presentation in Jekyll:
-
-`toclevels`::
-Changes how "deep" the TOC will be in terms of nested section/sub-section titles (default = `2`). Example: `:toclevels: 1`.
-
-`page-show-toc`::
-If this is `false`, then no TOCs will be generated for the page at all.
-The default is `true`, so can usually be left undefined.
-Example `:page-show-toc: false`.
-
-
-=== Layouts
-
-Layouts define the "look and feel" of each page.
-Jekyll uses https://shopify.github.io/liquid/[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 http://slim-lang.com/[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 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 next section).
-
-
-== Building the HTML Site
-
-A Gradle target `gradlew checkSite` will build the full HTML site (found in `solr/solr-ref-guide/build/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.
-
-The `checkSite` target also checks that all inter-doc references are correct and resolvable.
-See `solr/solr-ref-guide/tools/CheckLinksAndAnchors.java` for details of what that tool does to validate content.
diff --git a/dev-docs/ref-guide/publish.adoc b/dev-docs/ref-guide/publish.adoc
deleted file mode 100644
index e136c1c..0000000
--- a/dev-docs/ref-guide/publish.adoc
+++ /dev/null
@@ -1,131 +0,0 @@
-= Ref Guide Publication Process
-:toc:
-// 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
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-This section details how to build the Guide for publication.
-
-== Guide Publication Overview
-
-. Build and publish the DRAFT version.
-This is usually done as soon as the RC for a release is available.
-. Continue to update docs as needed while Solr artifact VOTE thread is ongoing.
-. After VOTE has passed, build and publish final version to overwrite DRAFT watermarked pages.
-
-== Pre-Requisites
-
-In order to build the Ref Guide, you must have the following:
-
-* You have checked out the Solr source code on the machine you will be doing the release from.
-* You have Subversion installed.
-This is needed for committing the HTML files to the production website repo.
-* All builds must be done from the release branch the Guide is for.
-
-NOTE: Build jobs are done by https://ci-builds.apache.org/job/Solr/[Jenkins] for relevant recent branches.
-The latest builds are stored in the https://nightlies.apache.org/solr/draft-guides/[ASF nightlies server].
-However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing.
-
-All dependencies for the build will be installed by Gradle, no local dependencies are required.
-
-== Build the DRAFT Guide
-
-The build process generates the page hierarchy and builds the HTML pages with custom templates the Solr project has defined.
-
-To build the HTML, from the top level of the project, run:
-
-[source,bash]
-$ ./gradlew clean solr:solr-ref-guide:buildSite
-
-This will produce pages with a DRAFT watermark across them.
-While these are fine for initial DRAFT publication, see the section <<Publish the Final Guide>> for steps to produce final production-ready HTML pages.
-
-The resulting Guide will be in `solr/solr-ref-guide/build`.
-The HTML files themselves will be in `solr/solr-ref-guide/build/html-site`.
-
-== Upload to the Website
-
-Push the Guide directly to production via Subversion `import` from where you built it.
-
-[source,bash]
-svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/solr-ref-guide/build/html-site https://svn.apache.org/repos/infra/sites/solr/guide/7_7
-
-Confirm you can browse to Guide manually by going to the new URL.
-For example: https://solr.apache.org/guide/7_7
-
-== 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.
-
-=== 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,pre-requisites>> from above.
-
-[source,bash]
-$ ./gradlew solr:solr-ref-guide:buildSite -PsolrGuideDraft=false
-
-IMPORTANT: The `-PsolrGuideDraft` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication).
-By default the build system assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages.
-Including the `-PsolrGuideDraft=false` property ensures the DRAFT watermark and labels are removed from the HTML files.
-
-*Pull Production Repo and Upload New Files*
-
-. Checkout the directory you need to update from the svn production repo:
-+
-[source,bash]
-$ svn co https://svn.apache.org/repos/infra/sites/solr/guide/<dir>
-+
-* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
-* Don't shortcut this and download the whole production website.
-It will take an incredibly long time and that will feel like _forever_.
-. Copy the files from the build location to the checked out Guide directory.
-For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/solr-ref-guide/build/html-site 7_7/.`
-. Use `svn status` to see the files modified.
-If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
-. Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"`
-
-*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).
-
-=== Link to the New Version from Solr 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*
-
-. Look at https://solr.staged.apache.org/guide and see if the RM already has updated it.
-If not, continue
-. You can check out and push changes or edit the file directly in GitHub: https://github.com/apache/solr-site/blob/main/content/pages/guide.md by clicking the edit button and then adding a commit message.
-. Verify that the staged version looks good (the link will not work in staging though)
-
-*Publish the changes to production*
-
-You can use your favourite git client to merge leader into branch `production`.
-Or you can use GitHub website:
-
-. Make a new pull request from https://github.com/apache/solr-site/compare/production%2E%2E%2Emain
-. 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 `SOLR_LATEST_RELEASE` property of the website, which will ensure that Ref Guide URLs without a version in the path (e.g., `/guide/mypage.adoc`) will automatically redirect to the latest Guide.
diff --git a/gradle/documentation/pull-lucene-javadocs.gradle b/gradle/documentation/pull-lucene-javadocs.gradle
index 73700f0..1172fdf 100644
--- a/gradle/documentation/pull-lucene-javadocs.gradle
+++ b/gradle/documentation/pull-lucene-javadocs.gradle
@@ -28,6 +28,8 @@ configure(project(":solr:documentation")) {
// Not sure why we need this, otherwise regular JARs get sucked in, not just
// javadoc-classifier JARs
transitive = false
+ canBeResolved = true
+ canBeConsumed = true
}
}
@@ -57,7 +59,7 @@ configure(project(":solr:documentation")) {
dependsOn configurations.javadocs
inputs.files configurations.javadocs
- outputs.dir luceneDocsDir
+ outputs.dir project.ext.luceneDocsDir
doFirst {
def resolved = configurations.javadocs.resolvedConfiguration
@@ -72,7 +74,7 @@ configure(project(":solr:documentation")) {
def path = id.name.replaceFirst('^lucene-', '').replaceFirst('^analysis-','analysis/')
project.sync {
from zipTree(artifact.file)
- into file("${luceneDocsDir}/${path}/")
+ into file("${project.ext.luceneDocsDir}/${path}/")
}
}
}
diff --git a/gradle/validation/ecj-lint.gradle b/gradle/validation/ecj-lint.gradle
index 0a7b044..8c72f9d 100644
--- a/gradle/validation/ecj-lint.gradle
+++ b/gradle/validation/ecj-lint.gradle
@@ -102,11 +102,3 @@ allprojects {
check.dependsOn ecjLint
}
}
-
-// This excludes solr-ref-guide from the check (excludes are not taken into account
-// and linting of the ant-based task fails.
-configure(project(":solr:solr-ref-guide")) {
- afterEvaluate {
- project.tasks.findByPath("ecjLintMain").enabled = false
- }
-}
diff --git a/gradle/validation/rat-sources.gradle b/gradle/validation/rat-sources.gradle
index 80d90a4..b6ba8bf 100644
--- a/gradle/validation/rat-sources.gradle
+++ b/gradle/validation/rat-sources.gradle
@@ -46,12 +46,14 @@ allprojects {
// At the module scope we only check selected file patterns as folks have various .gitignore-d resources
// generated by IDEs, etc.
- include "**/*.gradle"
include "**/*.xml"
include "**/*.md"
include "**/*.py"
include "**/*.sh"
include "**/*.bat"
+ // include build.gradle but exclude .gradle directories
+ include "**/*.gradle"
+ exclude ".gradle/**"
// Include selected patterns from any source folders. We could make this
// relative to source sets but it seems to be of little value - all our source sets
@@ -80,7 +82,6 @@ allprojects {
case ":":
include "gradlew"
include "gradlew.bat"
- exclude ".gradle"
exclude ".idea"
exclude ".muse"
exclude ".git"
@@ -141,6 +142,7 @@ allprojects {
case ":solr:solr-ref-guide":
exclude "src/**"
+ exclude "node_modules/**"
break
case ":solr:docker":
diff --git a/gradle/validation/validate-source-patterns.gradle b/gradle/validation/validate-source-patterns.gradle
index 3dc22f5..fa660d6 100644
--- a/gradle/validation/validate-source-patterns.gradle
+++ b/gradle/validation/validate-source-patterns.gradle
@@ -80,14 +80,11 @@ allprojects {
// default excludes.
exclude '**/build/**'
exclude '**/.idea/**'
+ exclude '**/.gradle/**'
if (project == rootProject) {
// ourselves :-)
exclude 'gradle/validation/validate-source-patterns.gradle'
-
- // gradle and idea folders.
- exclude '.gradle/**'
- exclude '.idea/**'
} else {
// ignore txt files in source resources and tests.
exclude 'src/**/*.txt'
@@ -117,6 +114,12 @@ configure(project(':solr:server')) {
}
}
+configure(project(':solr:solr-ref-guide')) {
+ project.tasks.withType(ValidateSourcePatternsTask) {
+ sourceFiles.exclude 'modules/indexing-guide/examples/stemdict.txt' // requires tabs
+ sourceFiles.exclude 'node_modules/**' // slightly hackish, this downloads all of the node deps
+ }
+}
class ValidateSourcePatternsTask extends DefaultTask {
private ProgressLoggerFactory progressLoggerFactory
diff --git a/solr/.gitignore b/solr/.gitignore
index e6e2e7e..d78365b 100644
--- a/solr/.gitignore
+++ b/solr/.gitignore
@@ -25,3 +25,5 @@
lib/
test-lib/
+
+/solr-ref-guide/node_modules/
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index f02b598..ecb833d 100644
--- a/solr/solr-ref-guide/README.adoc
+++ b/solr/solr-ref-guide/README.adoc
@@ -18,11 +18,14 @@
This is the source for the Solr Reference Guide.
-Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` directory.
+Raw content is stored in Asciidoc (`.adoc`) formatted files in the `modules/` directory.
-To build the Ref Guide, simply run `./gradlew checkSite`.
+To build the Ref Guide, simply run `./gradlew buildLocalSite`.
This will build the HTML files and validate that page references and internal links work properly.
+You can find the home page of the generated site under `build/site/index.html`
See the `../../dev-docs/ref-guide` directory for information about editing and publishing the Ref Guide.
To ignore the Ref Guide steps when running gradle `assemble` or `check`, use either `-Prefguide.include=false` or `SOLR_REF_GUIDE_INCLUDE=false`.
+
+If you want to test any changes for the Site UI files in `ui-src`, then use either `-Prefguide.buildLocalUI=false` or `SOLR_REF_GUIDE_BUILD_LOCAL_UI=false` when building the local or official site.
diff --git a/solr/solr-ref-guide/antora.template.yml b/solr/solr-ref-guide/antora.template.yml
new file mode 100644
index 0000000..0a7d8e2
--- /dev/null
+++ b/solr/solr-ref-guide/antora.template.yml
@@ -0,0 +1,36 @@
+name: solr
+version: '${solr_version_major}_${solr_version_minor}'
+display_version: '${solr_version_major}.${solr_version_minor}'
+# Marking a version as 'prerelease: true' is only needed for unpublished branches
+#prerelease: true
+title: Solr Reference Guide
+nav:
+- modules/getting-started/getting-started-nav.adoc
+- modules/deployment-guide/deployment-nav.adoc
+- modules/configuration-guide/config-nav.adoc
+- modules/indexing-guide/indexing-nav.adoc
+- modules/query-guide/querying-nav.adoc
+- modules/upgrade-notes/upgrade-nav.adoc
+
+# The asciidoc attributes must be the last entry in this file
+asciidoc:
+ attributes:
+ idseparator: '-'
+ idprefix: ''
+ # 'patch-version' is the 'z' part of x.y.z semantic version
+ page-solr-javadocs: '${solr_javadocs_link}'
+ solr-javadocs: '${solr_javadocs_link}'
+ lucene-javadocs: '${lucene_javadocs_link}'
+ java-javadocs: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/
+ # Some constructed links may be 404 TODO to check
+ solr-docs-version: '${solr_version_major}.${solr_version_minor}'
+ solr-full-version: '${solr_version}'
+
+ dep-version-commons-codec: '${dep_version_commons_codec}'
+ dep-version-dropwizard: '${dep_version_dropwizard}'
+ dep-version-hadoop: '${dep_version_hadoop}'
+ dep-version-log4j: '${dep_version_log4j}'
+ dep-version-opennlp: '${dep_version_opennlp}'
+ dep-version-tika: '${dep_version_tika}'
+ dep-version-zookeeper: '${dep_version_zookeeper}'
+ dep-version-lucene: '${dep_version_lucene}'
diff --git a/solr/solr-ref-guide/antora.yml b/solr/solr-ref-guide/antora.yml
new file mode 100644
index 0000000..27411b1
--- /dev/null
+++ b/solr/solr-ref-guide/antora.yml
@@ -0,0 +1,36 @@
+name: solr
+version: '10_0'
+display_version: '10.0'
+# Marking a version as 'prerelease: true' is only needed for unpublished branches
+#prerelease: true
+title: Solr Reference Guide
+nav:
+- modules/getting-started/getting-started-nav.adoc
+- modules/deployment-guide/deployment-nav.adoc
+- modules/configuration-guide/config-nav.adoc
+- modules/indexing-guide/indexing-nav.adoc
+- modules/query-guide/querying-nav.adoc
+- modules/upgrade-notes/upgrade-nav.adoc
+
+# The asciidoc attributes must be the last entry in this file
+asciidoc:
+ attributes:
+ idseparator: '-'
+ idprefix: ''
+ # 'patch-version' is the 'z' part of x.y.z semantic version
+ page-solr-javadocs: 'https://solr.apache.org/docs/10_0_0'
+ solr-javadocs: 'https://solr.apache.org/docs/10_0_0'
+ lucene-javadocs: 'https://lucene.apache.org/core/9_0_0'
+ java-javadocs: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/
+ # Some constructed links may be 404 TODO to check
+ solr-docs-version: '10.0'
+ solr-full-version: '10.0.0'
+
+ dep-version-commons-codec: '1.13'
+ dep-version-dropwizard: '4.1.5'
+ dep-version-hadoop: '3.2.0'
+ dep-version-log4j: '2.17.1'
+ dep-version-opennlp: '1.9.1'
+ dep-version-tika: '1.27'
+ dep-version-zookeeper: '3.7.0'
+ dep-version-lucene: '9.0.0'
diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle
index 74944db..013f0ab 100644
--- a/solr/solr-ref-guide/build.gradle
+++ b/solr/solr-ref-guide/build.gradle
@@ -15,276 +15,473 @@
* limitations under the License.
*/
-buildscript {
- repositories {
- mavenCentral()
- jcenter()
- }
-
- dependencies {
- classpath "org.asciidoctor:asciidoctorj:2.5.1"
- }
-}
+import org.apache.tools.ant.util.TeeOutputStream
plugins {
- id 'java'
- id 'com.github.jruby-gradle.base' version '2.0.1'
+ id "com.github.node-gradle.node" version "3.1.1"
}
-// This project does not contribute anything to main dependencies.
-versionsLock {
- testProject()
-}
+description = 'Solr Reference Guide'
-description = 'Solr reference guide'
+def buildLocalUI = propertyOrEnvOrDefault("refguide.buildLocalUI", "SOLR_REF_GUIDE_BUILD_LOCAL_UI", "false").toBoolean()
-// Use an internal proxy to ruby gems.
-repositories {
- ruby.gems()
+// Attach building the ref guide to standard convention tasks. This
+// can be optionally turned off (see SOLR-15670).
+if (propertyOrEnvOrDefault('refguide.include', 'SOLR_REF_GUIDE_INCLUDE', "true").toBoolean()) {
+ check.dependsOn 'checkSiteLinks'
+ assemble.dependsOn 'buildLocalSite'
}
configurations {
- depVer
refGuide
+ officialPlaybook
+ localPlaybook
}
dependencies {
- // Dependencies to compile internal tools.
- implementation('org.asciidoctor:asciidoctorj-api')
- implementation('org.asciidoctor:asciidoctorj')
- implementation('com.vaadin.external.google:android-json')
- implementation('org.jsoup:jsoup')
-
- // Dependencies referenced in the guide.
- depVer('commons-codec:commons-codec')
- depVer('io.dropwizard.metrics:metrics-core')
- depVer('org.apache.logging.log4j:log4j-core')
- depVer('org.apache.opennlp:opennlp-tools')
- depVer('org.apache.tika:tika-core')
- depVer('org.apache.zookeeper:zookeeper')
-
- // jekyll dependencies: we cannot use jekyll >=4, as this version uses native lib
- // ("sassc" instead of deprecated "sass") which fails to compile on some platforms.
- // See https://issues.apache.org/jira/browse/SOLR-15520 for more details.
- gems 'rubygems:jekyll:3.9.1'
- gems 'rubygems:jekyll-asciidoc:3.0.0'
-
- // don't know why we have to explicitly add these deps but it doesn't resolve them
- // automatically.
- gems 'rubygems:tilt:2.0.10'
- gems 'rubygems:slim:4.1.0'
- gems 'rubygems:concurrent-ruby:1.1.9'
- gems 'rubygems:http_parser.rb:0.6.0'
-
+ localPlaybook project(path: ":solr:documentation", configuration: 'javadocs')
+ localPlaybook project(path: ":solr:documentation", configuration: 'site')
+}
+ext {
+ antoraVersion = "3.0.1"
+ rootNodeDir = "${project.rootDir}/.gradle/node"
+ nodeProjectDir = file("${project.ext.rootNodeDir}/ref-guide-project")
+
+ siteDir = "${buildDir}/site"
+ antoraConfigBuildDir = "${buildDir}/antora-config"
+ playbooksDir = "${project.ext.antoraConfigBuildDir}/playbooks"
+ localAntoraYaml = "${project.ext.antoraConfigBuildDir}/antora.yml"
+ siteStagingDir = "${buildDir}/site-staging"
+ uiBuildDir = "${buildDir}/ui"
+ playbookTemplate = "playbook.template.yml"
+ localPlaybook = "local-playbook.yml"
+ officialPlaybook = "official-playbook.yml"
}
-sourceSets {
- refGuide {
- java {
- srcDirs = []
- }
- resources {
- srcDirs = ['src']
+/*
+ Generating the Antora and Playbook YAML files
+ */
+task buildLocalAntoraYaml {
+ group = 'Site - Local'
+ description "Creates an local antora.yml with all variables populated. Note: This will change the antora.yml in the repo, not a build folder."
+
+ def templateYaml = "antora.template.yml"
+
+ inputs.file(templateYaml)
+ outputs.file(project.ext.localAntoraYaml)
+
+ doLast {
+ def splitVersion = version.toString().split("\\p{Punct}")
+ def props = [
+ solr_version : "${splitVersion[0]}.${splitVersion[1]}.${splitVersion[2]}",
+ solr_version_major : splitVersion[0],
+ solr_version_minor : splitVersion[1],
+ solr_version_patch : splitVersion[2],
+ ]
+ // Set these dependency versions as lazy gstrings so that they're resolved after evaluation.
+ // These variable names must use underscores, not dashes or periods
+ props.putAll([
+ ["dep_version_commons_codec", "commons-codec", "commons-codec"],
+ ["dep_version_dropwizard", "io.dropwizard.metrics", "metrics-core"],
+ ["dep_version_hadoop", "org.apache.hadoop", "hadoop-auth"],
+ ["dep_version_log4j", "org.apache.logging.log4j", "log4j-core"],
+ ["dep_version_opennlp", "org.apache.opennlp", "opennlp-tools"],
+ ["dep_version_tika", "org.apache.tika", "tika-core"],
+ ["dep_version_zookeeper", "org.apache.zookeeper", "zookeeper"],
+ ["dep_version_lucene", "org.apache.lucene", "lucene-core"],
+ ].collectEntries { propKey, depGroup, depId -> [propKey, "${-> project.getVersion(depGroup, depId)}"] })
+
+ props.putAll([
+ solr_javadocs_link : "https://solr.apache.org/docs/${props.solr_version.replaceAll("\\.", "_")}",
+ lucene_javadocs_link : project(':solr:documentation').luceneDocUrl,
+ ])
+
+ copy {
+ from(templateYaml) {
+ rename {
+ "antora.yml"
+ }
+ }
+ into project.ext.antoraConfigBuildDir
+
+ expand(props)
}
}
+}
- main {
- java {
- srcDirs = ['tools']
+task buildLocalAntoraPlaybookYaml(type: Copy) {
+ group = 'Site - Local'
+ description "Creates ${project.ext.localPlaybook} to build and test the site locally"
+
+ from(project.ext.playbookTemplate) {
+ rename {
+ project.ext.localPlaybook
}
}
+ into project.ext.playbooksDir
+
+ def props = [
+ 'site_url' : "",
+ 'redirect_facility' : "static",
+ 'source_url' : project.rootDir,
+ 'source_branches' : "HEAD",
+ 'start_path' : project.rootDir.relativePath(file(project.ext.siteStagingDir)),
+ 'supplemental_files' : "${project.ext.nodeProjectDir}/node_modules/@antora/lunr-extension/supplemental_ui",
+ 'site_dir' : "./" + file(project.ext.siteStagingDir).relativePath(file(project.ext.siteDir)),
+ ]
- test {
- java {
- srcDirs = []
+ expand(props)
+ inputs.properties(props)
+}
+
+task buildOfficialAntoraPlaybookYaml(type: Copy) {
+ group = 'Site - Official'
+ description "Creates ${project.ext.officialPlaybook} to build the official Solr ref-guide"
+
+ from(project.ext.playbookTemplate) {
+ rename {
+ project.ext.officialPlaybook
}
}
+ into project.ext.playbooksDir
+
+ def props = [
+ 'site_url' : "https://solr.apache.org/guide",
+ 'redirect_facility' : "httpd",
+ 'source_url' : "https://github.com/apache/solr.git",
+ 'source_branches' : ["jira/solr-15556-antora"],
+ 'start_path' : 'solr/solr-ref-guide',
+ 'supplemental_files' : "${project.ext.nodeProjectDir}/node_modules/@antora/lunr-extension/supplemental_ui",
+ 'site_dir' : "./" + file(project.ext.playbooksDir).relativePath(file(project.ext.siteDir)),
+ ]
+
+ expand(props)
+ inputs.properties(props)
}
-ext {
- mainPage = "index"
-
- // the "MAJOR.MINOR" version of solr this guide is about (guides aren't specific to BUGFIX releases)
- // So on 'branch_9_9' where 'version' may be 9.9.0, 9.9.1, 9.9.9, etc..; solrDocsVersion = 9.9
- solrDocsVersion = "${version}".replaceAll(/^(\d+\.\d+)(|\..*)$/, "\$1")
-
- // the "MAJOR_MINOR" version as a path for publishing the guide
- // So on 'branch_9_9' where solrDocsVersion = 9.9; solrGuideVersionPath => 9_9
- solrGuideVersionPath = "${solrDocsVersion}".replaceAll(/^(\d+)\.(\d+)$/, "\$1_\$2")
-
- // these will be used to dynamically build up (nearly) identical tasks with consistent names
- // for building & link checking the ref guide. One using absolute URLs to javadocs, the
- // other using local paths that can be validated by the link checker.
- htmlSiteDetails =
- [name: 'Site',
- path: 'html-site',
- desc: 'HTML Site for publishing to the Solr website',
- props: [
- htmlSolrJavadocs: "https://solr.apache.org/docs/${solrGuideVersionPath}_0/",
- htmlLuceneJavadocs: project(':solr:documentation').luceneDocUrl
- ]
- ]
- linkCheckSiteDetails =
- [name: 'LocalJavadocLinksSite',
- path: 'local-jdoc-links-site',
- desc: 'Local Site for checking javadoc links',
-
- // NOTE: extra '../' because we'll in a sub-dir of buildDir that will be built later...
- props: [
- htmlSolrJavadocs : 'link:../' + buildDir.toPath().relativize(project(':solr:documentation').docroot.toPath()).toString().replace(File.separator, '/'),
- htmlLuceneJavadocs : 'link:../' + buildDir.toPath().relativize(project(':solr:documentation').luceneDocsDir.toPath()).toString().replace(File.separator, '/'),
- ]
-
- // TODO: (see full discussion in SOLR-15265)
- // Ref guide build should really depend on those javadocs it links to - then there would be no awkwardness and, ideally,
- // you could just sync the resources you need into the final structure (that's why I declared javadocs as an artifact).
- // This does entail some duplication (syncing between folders) but if it's reused in different places then it's fine.
- ]
+dependencies {
+ localPlaybook files("${project.ext.playbooksDir}/${project.ext.localPlaybook}") {
+ builtBy tasks.buildLocalAntoraPlaybookYaml
+ }
+ officialPlaybook files("${project.ext.playbooksDir}/${project.ext.officialPlaybook}") {
+ builtBy tasks.buildOfficialAntoraPlaybookYaml
+ }
}
-// dynamically define the 2 variations of each target that we need...
-[ htmlSiteDetails, linkCheckSiteDetails ].each{ details ->
- final def contentDir = file("${buildDir}/${details.path}-content")
- final def htmlDir = file("${buildDir}/${details.path}")
+/*
+ Downloading Build Tools
+ */
- tasks.create("prepare${details.name}Sources", PrepareSources) {
- // configure task properties.
- srcDir.set(project.sourceSets.refGuide.resources.srcDirs.first())
- outDir.set(contentDir)
+// We use Node to install and run Antora
+node {
+ download = true
+ version = "16.13.2" // LTS
- // Set these dependency versions as lazy gstrings so that they're resolved after evaluation.
- def dependencyProps = [
- ["ivyCommonsCodec", "commons-codec", "commons-codec"],
- ["ivyDropwizardMetrics", "io.dropwizard.metrics", "metrics-core"],
- ["ivyHadoop", "org.apache.hadoop", "hadoop-auth"],
- ["ivyLog4j", "org.apache.logging.log4j", "log4j-core"],
- ["ivyOpennlpTools", "org.apache.opennlp", "opennlp-tools"],
- ["ivyTika", "org.apache.tika", "tika-core"],
- ["ivyZookeeper", "org.apache.zookeeper", "zookeeper"],
- ].collectEntries { propKey, depGroup, depId -> [propKey, "${ -> project.getVersion(depGroup, depId) }"] }
+ // The directory where Node.js is unpacked (when download is true)
+ workDir = file("${project.ext.rootNodeDir}/nodejs")
- props.putAll([
- htmlOutDir: "../${details.path}",
- javadocLink : "https://docs.oracle.com/en/java/javase/11/docs/api/java.base/",
- solrGuideDraftStatus : propertyOrDefault('solrGuideDraft', "true").toBoolean() ? "DRAFT" : "",
- solrRootPath : project(':solr').projectDir.toString() + File.separator,
- solrDocsVersion : project.ext['solrDocsVersion'],
- solrGuideVersionPath : project.ext['solrGuideVersionPath'],
- solrFullVersion: project.version,
- buildDate : rootProject.ext['buildDate'],
- buildYear : rootProject.ext['buildYear'],
- * : details.props,
- * : dependencyProps
- ])
+ // The directory where npm is installed (when a specific version is defined)
+ npmWorkDir = file("${project.ext.rootNodeDir}/npm")
+
+ // The directory where yarn is installed (when a Yarn task is used)
+ yarnWorkDir = file("${project.ext.rootNodeDir}/yarn")
+
+ // The Node.js project directory location
+ // This is where the package.json file and node_modules directory are located
+ // By default it is at the root of the current project
+ nodeProjectDir = project.ext.nodeProjectDir
+}
+
+task downloadAntoraCli(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "@antora/cli@${project.ext.antoraVersion}"]
+
+ inputs.property("Antora version", project.ext.antoraVersion)
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/@antora/cli")
+}
+
+task downloadAntoraSiteGenerator(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "@antora/site-generator-default@${project.ext.antoraVersion}"]
+
+ inputs.property("Antora version", project.ext.antoraVersion)
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/@antora/site-generator-default")
+}
+
+task downloadAntoraLunrExtension(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "@antora/lunr-extension"]
+
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/@antora/lunr-extension")
+}
+
+task downloadAsciidoctorMathjaxExtension(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "@djencks/asciidoctor-mathjax"]
+
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/@djencks/asciidoctor-mathjax")
+}
+
+task downloadAntora {
+ group = 'Build Dependency Download'
+ description "Download all Antora build dependencies for site generation."
+
+ dependsOn tasks.downloadAntoraCli
+ dependsOn tasks.downloadAntoraSiteGenerator
+ dependsOn tasks.downloadAntoraLunrExtension
+ dependsOn tasks.downloadAsciidoctorMathjaxExtension
+}
+
+task downloadLinkValidator(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "link-checker"]
+
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/link-checker")
+}
+
+task downloadDefaultUITemplate(type: NpmTask) {
+ group = 'Build Dependency Download'
+ args = ["install", "gitlab:antora/antora-ui-default", "--include=dev"]
+
+ inputs.files("${project.ext.nodeProjectDir}/package.json")
+ outputs.dir("${project.ext.nodeProjectDir}/node_modules/@antora/ui-default")
+}
+
+task startUIBuildDir(type: Copy) {
+ group = 'Site - UI'
+ dependsOn tasks.downloadDefaultUITemplate
+
+ // Copy the antora latest default ui into the root folder, to mimick a new checkout of the default ui
+ with {
+ from "${project.ext.nodeProjectDir}/node_modules/@antora/ui-default"
+ duplicatesStrategy = 'EXCLUDE'
}
- task "build${details.name}"(type: com.github.jrubygradle.JRubyExec) {
- dependsOn "prepare${details.name}Sources"
- group "Documentation"
- description "Builds the ${details.desc}"
+ // Overwrite the parts of the UI that we have changed.
+ from("${projectDir}/ui-src") {
+ into "src"
+ }
+ duplicatesStrategy = 'INCLUDE'
+
+ into project.ext.uiBuildDir
+}
- outputs.cacheIf { true }
- inputs.dir contentDir
- outputs.dir htmlDir
+task setupUIBuildDir(type: NpmTask) {
+ group = 'Site - UI'
+ dependsOn tasks.startUIBuildDir
+ workingDir = file(project.ext.uiBuildDir)
+ args = ["install"]
- script 'jekyll'
- scriptArgs 'build' //, '--verbose'
- workingDir contentDir
+ inputs.files("${project.ext.uiBuildDir}/package.json")
+ outputs.dir("${project.ext.uiBuildDir}/node_modules/")
+}
+
+// Note that Gulp must be installed in the UI Build Directory, not our project node_modules
+task downloadGulp(type: NpmTask) {
+ group = 'Build Dependency Download'
+ dependsOn tasks.startUIBuildDir
+
+ args = ["install", "gulp-cli", "--legacy-peer-deps"]
+ execOverrides {
+ // The it variable contains the `ExecSpec`
+ workingDir = project.ext.uiBuildDir
}
- task "check${details.name}"(type: JavaExec) {
- dependsOn "build${details.name}"
+ inputs.property("Antora version", project.ext.antoraVersion)
+ inputs.files("${project.ext.uiBuildDir}/package.json")
+ outputs.dir("${project.ext.uiBuildDir}/node_modules/")
+}
- classpath = sourceSets.main.runtimeClasspath
- main = 'org.apache.solr.guide.CheckLinksAndAnchors'
- workingDir = contentDir
+/*
+ Build and/or validate the Site
+ */
+
+task buildUIBundle(type: NpxTask) {
+ group = 'Site - UI'
+ description "Creates a local UI bundle using the 'ui-src' directory. This can be used to preview UI changes with a local or official ref-guide build."
+
+ dependsOn tasks.setupUIBuildDir
+ dependsOn tasks.downloadGulp
- // NOTE: even for the 'real' site, we check all relative links
- // (there will just be less of them, and this way any stray hardcoded
- // '../../' paths can be caught more easily)
- args([ htmlDir, "-check-all-relative-links" ])
+ command = "gulp"
+
+ args = [
+ "bundle",
+ ]
+ execOverrides {
+ // The it variable contains the `ExecSpec`
+ workingDir = project.ext.uiBuildDir
+ }
+
+ doLast {
+ copy {
+ from "${project.ext.uiBuildDir}/build/ui-bundle.zip"
+ into "${buildDir}/dist"
+ }
+ }
+
+ inputs.files(fileTree("${project.ext.uiBuildDir}/src"))
+ outputs.file("${buildDir}/dist/ui-bundle.zip")
+
+ doLast {
+ project.logger.lifecycle("The generated ui-bundle.zip can be found at:")
+ project.logger.lifecycle("\t${buildDir}/dist/ui-bundle.zip")
}
}
-// Hook in our dependency on all top level documentation in order to check local javadoc links
-checkLocalJavadocLinksSite.dependsOn ':documentation'
+task setupLocalSiteStagingDir(type: Sync) {
+ group = 'Site - Local'
+ description "Creates a staging directory to build the local ref-guide."
-// Attach building the ref guide to standard convention tasks. This
-// can be optionally turned off (see SOLR-15670).
-if (propertyOrEnvOrDefault('refguide.include', 'SOLR_REF_GUIDE_INCLUDE', "true").toBoolean()) {
- check.dependsOn checkLocalJavadocLinksSite, checkSite
- assemble.dependsOn buildSite
+ dependsOn tasks.buildLocalAntoraYaml
+ dependsOn configurations.localPlaybook
+
+ from(projectDir) {
+ include "modules/**"
+ }
+ from project.ext.localAntoraYaml
+ from(project.ext.playbooksDir) {
+ include project.ext.localPlaybook
+ rename {
+ "playbook.yml"
+ }
+ }
+
+ into project.ext.siteStagingDir
}
-@CacheableTask
-abstract class PrepareSources extends DefaultTask {
- // Original Source files we'll be syncing <b>FROM</b>
- @InputDirectory
- @PathSensitive(PathSensitivity.RELATIVE)
- abstract DirectoryProperty getSrcDir()
-
- // Destination folder.
- @OutputDirectory
- abstract DirectoryProperty getOutDir()
-
- /**
- * Task specific props (lazy provider)
- */
- @Input
- abstract MapProperty<String, String> getProps()
-
- public PrepareSources() {
- // setup 'dependsOn classes, configurations.depVer' here
- // so that it's not necessary for every task impl to declare redundantly
- final Project p = getProject()
- dependsOn(p.getConfigurations().getByName('depVer'))
- dependsOn(p.getTasksByName('classes', false))
+task buildLocalSite(type: NpxTask) {
+ group = 'Site - Local'
+ description "Creates a local build of the ref-guide."
+
+ dependsOn tasks.downloadAntora
+ dependsOn tasks.setupLocalSiteStagingDir
+
+ command = "antora"
+
+ // Use a local build of the Lucene and Solr javadocs for a local refGuide
+ def extraArgs = [
+ // This attribute should not include ":link", the other 2 should
+ // This attribute should also not be relative, because it is used in multiple path directories in the site
+ "--attribute", "page-solr-javadocs=${project(':solr:documentation').docroot.toPath()}",
+ "--attribute", "solr-javadocs=link:../../../${file(project.ext.siteDir).relativePath(project(':solr:documentation').docroot)}",
+ "--attribute", "lucene-javadocs=link:../../../${file(project.ext.siteDir).relativePath(project(':solr:documentation').luceneDocsDir)}"
+ ]
+
+ if (buildLocalUI) {
+ dependsOn tasks.buildUIBundle
+ extraArgs.addAll([
+ "--ui-bundle-url", "${buildDir}/dist/ui-bundle.zip"
+ ])
+ inputs.files("${buildDir}/dist/ui-bundle.zip")
+ }
+
+ args = [
+ "${project.ext.siteStagingDir}/playbook.yml",
+ "--fetch"
+ ] + extraArgs
+
+ environment = ["SITE_SEARCH_ENABLED": "true"]
+
+ inputs.files(fileTree(project.ext.siteStagingDir))
+ inputs.property("Antora version", project.ext.antoraVersion)
+ outputs.dir(project.ext.siteDir)
+
+ doLast {
+ project.logger.lifecycle("The generated local ref-guide can be found at:")
+ project.logger.lifecycle("\t${project.ext.siteDir}")
+ }
+}
+
+task checkSiteLinks(type: NpxTask) {
+ group = 'Verification'
+ description "Check that all links in the ref-guide, both internal and java-docs, are correct."
+
+ dependsOn tasks.downloadLinkValidator
+ dependsOn tasks.buildLocalSite
+
+ command = "link-checker"
+ args = [
+ "${buildDir}/site",
+ "--url-ignore", "file:/",
+ "--mkdocs",
+ "--allow-hash-href",
+ "--disable-external",
+ "--debug",
+ // Ignore the java docs url in the header, since it is an absolute path
+ "--url-ignore", "${project(':solr:documentation').docroot.toPath()}/index\\.html",
+ "--json",
+ "-v",
+ ]
+
+ def outputFile = "${buildDir}/validation/link-check.json"
+ execOverrides {
+ // The it variable contains the `ExecSpec`
+ it.standardOutput = new TeeOutputStream(it.standardOutput, new FileOutputStream(outputFile))
}
- @TaskAction
- public void doCopy() {
- final Project p = getProject();
-
- // Make a local copy we'll be modifying.
- final def props = this.props.get()
-
- final File intoDir = this.outDir.asFile.get();
-
- // Emit info about properties for clarity.
- logger.lifecycle('Syncing source files to {} using props:\n{}',
- intoDir, props.collect({ k, v -> " ${k} -> ${v}" }).join('\n'))
-
- // Escape all the properties, so they can be inserted into YAML templates.
- final def escapedProps = props.collectEntries{k, v -> [k, v.replace("'","''")]}
-
- def sourceDir = srcDir.get()
-
- final WorkResult syncResult = p.sync({ copySpec ->
- copySpec.setFilteringCharset('UTF-8');
- copySpec.from(sourceDir, { raw ->
- raw.exclude('**/*.template')
- })
-
- copySpec.from(sourceDir, { templated ->
- templated.include('**/*.template')
- templated.rename('(.+)\\.template', '$1')
- templated.expand(escapedProps)
- })
- copySpec.into(intoDir);
- })
-
- setDidWork(syncResult.getDidWork());
- if (syncResult.getDidWork()) {
- // if sync did work, that means we need to rebuild the nav data files...
- p.javaexec({ execSpec ->
- execSpec.setClasspath( getProject().getConvention()
- .getPlugin(JavaPluginConvention.class)
- .getSourceSets().getByName("main").getRuntimeClasspath() )
- execSpec.setWorkingDir( intoDir )
- execSpec.setMain( 'org.apache.solr.guide.BuildNavDataFiles' )
- execSpec.args([ intoDir, p.property('mainPage') ])
- })
+ inputs.files(fileTree(siteDir))
+ outputs.file(outputFile)
+}
+
+/*
+ Build and setup the official Site
+ */
+task setOfficialAntoraYaml {
+ group = 'Site - Official'
+ description "Setups the local antora.yml as the official antora.yml for this branch. Note: This will change the antora.yml in the repo, not a build folder."
+
+ dependsOn tasks.buildLocalAntoraYaml
+
+ inputs.file(project.ext.localAntoraYaml)
+ outputs.file("antora.yml")
+
+ doLast {
+ copy {
+ from project.ext.localAntoraYaml
+ into projectDir
}
}
}
+
+task buildOfficialSite(type: NpxTask) {
+ group = 'Site - Official'
+ description "Creates a build of the official ref-guide. This will not include local changes."
+
+ dependsOn tasks.downloadAntora
+ dependsOn configurations.officialPlaybook
+
+ command = "antora"
+
+ def officialPlaybook = "${project.ext.playbooksDir}/${project.ext.officialPlaybook}"
+ def extraArgs = []
+
+ if (buildLocalUI) {
+ dependsOn tasks.buildUIBundle
+ extraArgs.addAll([
+ "--ui-bundle-url", "${buildDir}/dist/ui-bundle.zip"
+ ])
+ inputs.files("${buildDir}/dist/ui-bundle.zip")
+ }
+
+ args = [
+ officialPlaybook,
+ ] + extraArgs
+
+ environment = ["SITE_SEARCH_ENABLED": "true"]
+
+ inputs.files(officialPlaybook)
+ inputs.property("Antora version", project.ext.antoraVersion)
+ outputs.dir(project.ext.siteDir)
+
+ doLast {
+ project.logger.lifecycle("The generated official ref-guide can be found at:")
+ project.logger.lifecycle("\t${project.ext.siteDir}")
+ }
+}
diff --git a/solr/solr-ref-guide/src/images/Solr_Logo_on_white.png b/solr/solr-ref-guide/modules/ROOT/images/Solr_Logo_on_white.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/Solr_Logo_on_white.png
rename to solr/solr-ref-guide/modules/ROOT/images/Solr_Logo_on_white.png
diff --git a/solr/solr-ref-guide/src/images/diagrams/splitshard-seq.png b/solr/solr-ref-guide/modules/ROOT/images/diagrams/splitshard-seq.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/diagrams/splitshard-seq.png
rename to solr/solr-ref-guide/modules/ROOT/images/diagrams/splitshard-seq.png
diff --git a/solr/solr-ref-guide/src/images/diagrams/splitshard-seq.puml b/solr/solr-ref-guide/modules/ROOT/images/diagrams/splitshard-seq.puml
similarity index 100%
rename from solr/solr-ref-guide/src/images/diagrams/splitshard-seq.puml
rename to solr/solr-ref-guide/modules/ROOT/images/diagrams/splitshard-seq.puml
diff --git a/solr/solr-ref-guide/src/images/draft-background.png b/solr/solr-ref-guide/modules/ROOT/images/draft-background.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/draft-background.png
rename to solr/solr-ref-guide/modules/ROOT/images/draft-background.png
diff --git a/solr/solr-ref-guide/src/images/icons/bullet_blue.gif b/solr/solr-ref-guide/modules/ROOT/images/icons/bullet_blue.gif
similarity index 100%
rename from solr/solr-ref-guide/src/images/icons/bullet_blue.gif
rename to solr/solr-ref-guide/modules/ROOT/images/icons/bullet_blue.gif
diff --git a/solr/solr-ref-guide/src/images/icons/contenttypes/home_page_16.png b/solr/solr-ref-guide/modules/ROOT/images/icons/contenttypes/home_page_16.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/icons/contenttypes/home_page_16.png
rename to solr/solr-ref-guide/modules/ROOT/images/icons/contenttypes/home_page_16.png
diff --git a/solr/solr-ref-guide/src/images/icons/emoticons/warning.png b/solr/solr-ref-guide/modules/ROOT/images/icons/emoticons/warning.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/icons/emoticons/warning.png
rename to solr/solr-ref-guide/modules/ROOT/images/icons/emoticons/warning.png
diff --git a/solr/solr-ref-guide/src/images/icons/favicon.ico b/solr/solr-ref-guide/modules/ROOT/images/icons/favicon.ico
similarity index 100%
copy from solr/solr-ref-guide/src/images/icons/favicon.ico
copy to solr/solr-ref-guide/modules/ROOT/images/icons/favicon.ico
diff --git a/solr/solr-ref-guide/src/images/solr-sunOnly-small.png b/solr/solr-ref-guide/modules/ROOT/images/solr-sunOnly-small.png
similarity index 100%
copy from solr/solr-ref-guide/src/images/solr-sunOnly-small.png
copy to solr/solr-ref-guide/modules/ROOT/images/solr-sunOnly-small.png
diff --git a/solr/solr-ref-guide/modules/ROOT/pages/index.adoc b/solr/solr-ref-guide/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000..373a39b
--- /dev/null
+++ b/solr/solr-ref-guide/modules/ROOT/pages/index.adoc
@@ -0,0 +1,50 @@
+= Apache Solr Reference Guide
+:page-show-toc: false
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// This jumbotron is in a sidebar-style block instead of an open block because
+// an open block uses a different template that we rely on for other uses.
+// See also src/_templates/open.html.slim for the open block template.
+.Welcome to Apache Solr(TM)
+****
+Solr is the open source solution for search and analytics.
+
+A fast open source search platform built on Apache Lucene(TM), Solr provides scalable indexing and search, as well as faceting, hit highlighting and advanced analysis/tokenization capabilities.
+Solr is managed by the http://www.apache.org/[Apache Software Foundation].
+
+This Reference Guide is the official Solr documentation, written and published by Solr committers.
+****
+
+****
+[cols="1,1,1",frame=none,grid=none,stripes=none]
+|===
+^| xref:getting-started:introduction.adoc[Getting Started] ^| xref:deployment-guide:solr-control-script-reference.adoc[Deployment Guide] ^| xref:configuration-guide:configuration-files.adoc[Configuration Guide]
+
+| Introductory concepts and tutorials. | Installation, monitoring, scaling, and deploying to production. | Tuning Solr's configuration files for your use case.
+
+|===
+
+[.home-table,cols="1,1,1",frame=none,grid=none,stripes=none]
+|===
+^| xref:indexing-guide:schema-elements.adoc[Indexing Guide] ^| xref:query-guide:common-query-parameters.adoc[Query Guide] ^| xref:upgrade-notes:solr-upgrade-notes.adoc[Upgrade Notes]
+
+| Configuring Solr's schema and indexing documents. | All aspects of Solr queries. | Change notes for Solr releases.
+
+|===
+
+****
diff --git a/solr/solr-ref-guide/modules/configuration-guide/config-nav.adoc b/solr/solr-ref-guide/modules/configuration-guide/config-nav.adoc
new file mode 100644
index 0000000..2c4e942
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/config-nav.adoc
@@ -0,0 +1,40 @@
+.Configuration Guide
+
+* xref:configuration-files.adoc[]
+* xref:property-substitution.adoc[]
+* xref:core-discovery.adoc[]
+* xref:configuring-solr-xml.adoc[]
+
+* xref:configuring-solrconfig-xml.adoc[]
+** xref:index-location-format.adoc[]
+** xref:index-segments-merging.adoc[]
+** xref:schema-factory.adoc[]
+** xref:commits-transaction-logs.adoc[]
+** xref:caches-warming.adoc[]
+** xref:requesthandlers-searchcomponents.adoc[]
+** xref:implicit-requesthandlers.adoc[]
+** xref:realtime-get.adoc[]
+** xref:initparams.adoc[]
+** xref:requestdispatcher.adoc[]
+** xref:update-request-processors.adoc[]
+** xref:script-update-processor.adoc[]
+** xref:codec-factory.adoc[]
+
+* Configuration APIs
+** xref:config-api.adoc[]
+** xref:request-parameters-api.adoc[]
+** xref:managed-resources.adoc[]
+** xref:collections-api.adoc[]
+** xref:configsets-api.adoc[]
+** xref:coreadmin-api.adoc[]
+** xref:v2-api.adoc[]
+
+* xref:config-sets.adoc[]
+* xref:resource-loading.adoc[]
+* xref:solr-plugins.adoc[]
+** xref:libs.adoc[]
+** xref:solr-modules.adoc[]
+** xref:package-manager.adoc[]
+*** xref:package-manager-internals.adoc[]
+** xref:cluster-plugins.adoc[]
+** xref:replica-placement-plugins.adoc[]
diff --git a/solr/solr-ref-guide/src/images/configuration-files/files-screen.png b/solr/solr-ref-guide/modules/configuration-guide/images/configuration-files/files-screen.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/configuration-files/files-screen.png
rename to solr/solr-ref-guide/modules/configuration-guide/images/configuration-files/files-screen.png
diff --git a/solr/solr-ref-guide/src/images/index-segments-merging/segments_info.png b/solr/solr-ref-guide/modules/configuration-guide/images/index-segments-merging/segments_info.png
similarity index 100%
rename from solr/solr-ref-guide/src/images/index-segments-merging/segments_info.png
rename to solr/solr-ref-guide/modules/configuration-guide/images/index-segments-merging/segments_info.png
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/caches-warming.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/caches-warming.adoc
new file mode 100644
index 0000000..23197c7
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/caches-warming.adoc
@@ -0,0 +1,343 @@
+= Caches and Query Warming
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Solr's caches provide an essential way to improve query performance.
+Caches can store documents, filters used in queries, and results from previous queries.
+
+Caches are cleared after a xref:commits-transaction-logs.adoc#commits[commit] and usually need to be re-populated before their benefit can be seen again.
+To counteract this, caches can be "warmed" before a new searcher is considered opened by automatically populating the new cache with values from the old cache.
+
+Cache management is critical to a successful Solr implementation, so it should be noted that caches will need to be fine-tuned as your application grows.
+
+== <query> in solrconfig.xml
+
+The settings in this section affect the way that Solr will process and respond to queries.
+
+These settings are all configured in child elements of the `<query>` element in `solrconfig.xml`.
+
+[source,xml]
+----
+<config>
+ <query>
+ ...
+ </query>
+</config>
+----
+
+== Caches
+
+Solr caches are associated with a specific instance of an Index Searcher, a specific view of an index that doesn't change during the lifetime of that searcher.
+As long as that Index Searcher is being used, any items in its cache will be valid and available for reuse.
+By default cached Solr objects do not expire after a time interval; instead, they remain valid for the lifetime of the Index Searcher.
+Idle time-based expiration can be enabled by using `maxIdleTime` option.
+
+When a new searcher is opened, the current searcher continues servicing requests while the new one auto-warms its cache.
+The new searcher uses the current searcher's cache to pre-populate its own.
+When the new searcher is ready, it is registered as the current searcher and begins handling all new search requests.
+The old searcher will be closed once it has finished servicing all its requests.
+
+=== Cache Implementations
+
+Solr comes with a default `SolrCache` implementation that is used for different types of caches.
+
+The `CaffeineCache` is an implementation backed by the https://github.com/ben-manes/caffeine[Caffeine caching library].
+By default it uses a Window TinyLFU (W-TinyLFU) eviction policy, which allows the eviction based on both frequency and recency of use in O(1) time with a small footprint.
+Generally this cache usually offers lower memory footprint, higher hit ratio, and better multi-threaded performance over legacy caches.
+
+`CaffeineCache` uses an auto-warm count that supports both integers and percentages which get evaluated relative to the current size of the cache when warming happens.
+
+The xref:deployment-guide:plugins-stats-screen.adoc[] in the Solr Admin UI will display information about the performance of all the active caches.
+This information can help you fine-tune the sizes of the various caches appropriately for your particular application.
+When a Searcher terminates, a summary of its cache usage is also written to the log.
+
+=== Cache Parameters
+
+Each cache has settings to define its initial size (`initialSize`), maximum size (`size`), and number of items to use for during warming (`autowarmCount`).
+For `autowarmCount` this can be also expressed as a percentage instead of an absolute value.
+
+A `maxIdleTime` attribute controls the automatic eviction of entries that haven't been used for a while.
+This attribute is expressed in seconds, with the default value of `0` meaning no entries are automatically evicted due to exceeded idle time.
+Smaller values of this attribute will cause older entries to be evicted quickly, which will reduce cache memory usage but may instead cause thrashing due to a repeating eviction-lookup-miss-insertion cycle of the same entries.
+Larger values will cause entries to stay around longer, waiting to be reused, at the cost of increased memory usage.
+Reasonable values, depending on the query volume and patterns, may lie somewhere between 60-3600.
+
+The `maxRamMB` attribute limits the maximum amount of memory a cache may consume.
+When both `size` and `maxRamMB` limits are specified the `maxRamMB` limit will take precedence and the `size` limit will be ignored.
+
+The `async` attribute determines whether the cache stores direct results (`async=false`, disabled) or whether it will store indirect references to the computation (`async=true`, enabled by default).
+If your queries include child documents or join queries, then async cache must be enabled to function properly.
+Disabling the async option may use slightly less memory per cache entry at the expense of increased CPU.
+The async cache provides most significant improvement with many concurrent queries requesting the same result set that has not yet been cached, as an alternative to larger cache sizes or increased auto-warming counts.
+However, the async cache will not prevent data races for time-limited queries, since those are expected to provide partial results.
+
+All caches can be disabled using the parameter `enabled` with a value of `false`.
+Caches can also be disabled on a query-by-query basis with the `cache` parameter, as described in the section xref:query-guide:common-query-parameters.adoc#cache-local-parameter[cache Local Parameter].
+
+Details of each cache are described below.
+
+=== Filter Cache
+
+This cache holds parsed queries paired with an unordered set of all documents that match it.
+Unless such a set is trivially small, the set implementation is a bitset.
+
+The most typical way Solr uses the `filterCache` is to cache results of each `fq` search parameter, though there are some other cases as well.
+Subsequent queries using the same parameter filter query result in cache hits and rapid returns of results.
+See xref:query-guide:common-query-parameters.adoc#fq-filter-query-parameter[fq (Filter Query) Parameter] for a detailed discussion of `fq`.
+Use of this cache can be disabled for a `fq` using the xref:query-guide:common-query-parameters.adoc#cache-local-parameter[`cache` local parameter].
+
+Another Solr feature using this cache is the `filter(...)` syntax in the default Lucene query parser.
+
+Solr also uses this cache for faceting when the configuration parameter `facet.method` is set to `fc`.
+For a discussion of faceting parameters, see xref:query-guide:faceting.adoc#field-value-faceting-parameters[Field-Value Faceting Parameters].
+
+[source,xml]
+----
+<filterCache class="solr.CaffeineCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="128"/>
+----
+
+The cache supports a `maxRamMB` parameter which restricts the maximum amount of heap used by this cache.
+The `CaffeineCache` only supports evictions by either heap usage or size, but not both.
+Therefore, the `size` parameter is ignored if `maxRamMB` is specified.
+
+[source,xml]
+----
+<filterCache class="solr.CaffeineCache"
+ maxRamMB="1000"
+ autowarmCount="128"/>
+----
+
+The filter cache is a good candidate for enabling `async` computation.
+
+[source,xml]
+----
+<filterCache class="solr.CaffeineCache"
+ size="1024"
+ autowarmCount="0"
+ async="true"/>
+----
+
+
+=== Query Result Cache
+
+The `queryResultCache` holds the results of previous searches: ordered lists of document IDs (DocList) based on a query, a sort, and the range of documents requested.
+
+The `queryResultCache` has an optional setting to limit the maximum amount of RAM used (`maxRamMB`).
+This lets you specify the maximum heap size, in megabytes, used by the contents of this cache.
+When the cache grows beyond this size, oldest accessed queries will be evicted until the heap usage of the cache decreases below the specified limit.
+If a `size` is specified in addition to `maxRamMB` then only the heap usage limit is respected.
+
+Use of this cache can be disabled on a query-by-query basis in `q` using the xref:query-guide:common-query-parameters.adoc#cache-local-parameter[`cache` local parameter].
+
+[source,xml]
+----
+<queryResultCache class="solr.CaffeineCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="128"/>
+----
+
+=== Document Cache
+
+The `documentCache` holds Lucene Document objects (the stored fields for each document).
+Since Lucene internal document IDs are transient, this cache is not auto-warmed.
+
+The size for the `documentCache` should always be greater than `max_results` times the `max_concurrent_queries`, to ensure that Solr does not need to refetch a document during a request.
+The more fields you store in your documents, the higher the memory usage of this cache will be.
+
+[source,xml]
+----
+<documentCache class="solr.CaffeineCache"
+ size="512"
+ initialSize="512"
+ autowarmCount="0"/>
+----
+
+=== User Defined Caches
+
+You can also define named caches for your own application code to use.
+You can locate and use your cache object by name by calling the `SolrIndexSearcher` methods `getCache()`, `cacheLookup()` and `cacheInsert()`.
+
+[source,xml]
+----
+<cache name="myUserCache" class="solr.CaffeineCache"
+ size="4096"
+ initialSize="1024"
+ autowarmCount="1024"
+ regenerator="org.mycompany.mypackage.MyRegenerator" />
+----
+
+If you want auto-warming of your cache, include a `regenerator` attribute with the fully qualified name of a class that implements {solr-javadocs}/core/org/apache/solr/search/CacheRegenerator.html[`solr.search.CacheRegenerator`].
+You can also use the `NoOpRegenerator`, which simply repopulates the cache with old items.
+Define it with the `regenerator` parameter as `regenerator="solr.NoOpRegenerator"`.
+
+=== Monitoring Cache Sizes and Usage
+
+The section xref:deployment-guide:performance-statistics-reference.adoc#cache-statistics[Cache Statistics] describes the metrics available for each cache.
+The metrics can be accessed in the xref:deployment-guide:plugins-stats-screen.adoc[] or with the xref:deployment-guide:metrics-reporting.adoc#metrics-api[Metrics API].
+
+The most important metrics to review when assessing caches are the size and the hit ratio.
+
+The size indicates how many items are in the cache.
+Some caches support setting the maximum cache size in MB of RAM.
+
+The hit ratio is a percentage of queries served by the cache, shown as a number between 0 and 1.
+Higher values indicate that the cache is being used often, while lower values would show that the cache isn't helping queries very much.
+Ideally, this number should be as close to 1 as possible.
+
+If you find that you have a low hit ratio but you've set your cache size high, you can optimize by reducing the cache size - there's no need to keep those objects in memory when they are not being used.
+
+Another useful metric is the cache evictions, which measures the objects removed from the cache.
+A high rate of evictions can indicate that your cache is too small and increasing it may show a higher hit ratio.
+Alternatively, if your hit ratio is high but your evictions are low, your cache might be too large and you may benefit from reducing the size.
+
+A low hit ratio is not always a sign of a specific cache problem.
+If your queries are not repeated often, a low hit ratio would be expected because it's less likely that cached objects will need to be reused.
+In these cases, a smaller cache size may be ideal for your system.
+
+== Query Sizing and Warming
+
+Several elements are available to control the size of queries and how caches are warmed.
+
+=== <maxBooleanClauses> Element
+
+Sets the maximum number of clauses allowed when parsing a boolean query string.
+
+This limit only impacts boolean queries specified by a user as part of a query string, and provides per-collection controls on how complex user specified boolean queries can be.
+Query strings that specify more clauses than this will result in an error.
+
+If this per-collection limit is greater than the xref:configuring-solr-xml.adoc#global-maxbooleanclauses[global `maxBooleanClauses` limit] specified in `solr.xml`, it will have no effect, as that setting also limits the size of user specified boolean queries.
+
+In default configurations this property uses the value of the `solr.max.booleanClauses` system property if specified.
+This is the same system property used in the xref:configuring-solr-xml#global-maxbooleanclauses[global `maxBooleanClauses` setting] in the default `solr.xml` making it easy for Solr administrators to increase both values (in all collections) without needing to search through and update the `solrconfig.xml` files in each collection.
+
+[source,xml]
+----
+<maxBooleanClauses>${solr.max.booleanClauses:1024}</maxBooleanClauses>
+----
+
+=== <enableLazyFieldLoading> Element
+
+When this parameter is set to `true`, fields that are not directly requested will be loaded only as needed.
+
+This can boost performance if the most common queries only need a small subset of fields, especially if infrequently accessed fields are large in size.
+
+[source,xml]
+----
+<enableLazyFieldLoading>true</enableLazyFieldLoading>
+----
+
+=== <useFilterForSortedQuery> Element
+
+This parameter configures Solr to use a filter to satisfy a search.
+If the requested sort does not include "score", the `filterCache` will be checked for a filter matching the query.
+For most situations, this is only useful if the same search is requested often with different sort options and none of them ever use "score".
+
+[source,xml]
+----
+<useFilterForSortedQuery>true</useFilterForSortedQuery>
+----
+
+=== <queryResultWindowSize> Element
+
+Used with the `queryResultCache`, this will cache a superset of the requested number of document IDs.
+
+For example, if a query requests documents 10 through 19, and `queryWindowSize` is 50, documents 0 through 49 will be cached.
+
+[source,xml]
+----
+<queryResultWindowSize>20</queryResultWindowSize>
+----
+
+=== <queryResultMaxDocsCached> Element
+
+This parameter sets the maximum number of documents to cache for any entry in the `queryResultCache`.
+
+[source,xml]
+----
+<queryResultMaxDocsCached>200</queryResultMaxDocsCached>
+----
+
+=== <useColdSearcher> Element
+
+This setting controls whether search requests for which there is not a currently registered searcher should wait for a new searcher to warm up (`false`) or proceed immediately (`true`).
+When set to "false`, requests will block until the searcher has warmed its caches.
+
+[source,xml]
+----
+<useColdSearcher>false</useColdSearcher>
+----
+
+=== <maxWarmingSearchers> Element
+
+This parameter sets the maximum number of searchers that may be warming up in the background at any given time.
+Exceeding this limit will raise an error.
+
+For read-only followers, a value of `2` is reasonable.
+Leaders should probably be set a little higher.
+
+[source,xml]
+----
+<maxWarmingSearchers>2</maxWarmingSearchers>
+----
+
+== Query-Related Listeners
+
+As described in the section on <<Caches>>, new Searchers are cached.
+It's possible to use the triggers for listeners to perform query-related tasks.
+The most common use of this is to define queries to further "warm" the Searchers while they are starting.
+One benefit of this approach is that field caches are pre-populated for faster sorting.
+
+Good query selection is key with this type of listener.
+It's best to choose your most common and/or heaviest queries and include not just the keywords used, but any other parameters such as sorting or filtering requests.
+
+There are two types of events that can trigger a listener.
+
+. A `firstSearcher` event occurs when a new searcher is being prepared but there is no current registered searcher to handle requests or to gain auto-warming data from (i.e., on Solr startup).
+. A `newSearcher` event is fired whenever a new searcher is being prepared, such as after a commit, and there is a current searcher handling requests.
+
+The (commented out) examples below can be found in the `solrconfig.xml` file of the `sample_techproducts_configs` xref:config-sets.adoc[configset] included with Solr, and demonstrate using the `solr.QuerySenderListener` class to warm a set of explicit queries:
+
+[source,xml]
+----
+<listener event="newSearcher" class="solr.QuerySenderListener">
+ <arr name="queries">
+ <!--
+ <lst><str name="q">solr</str><str name="sort">price asc</str></lst>
+ <lst><str name="q">rocks</str><str name="sort">weight asc</str></lst>
+ -->
+ </arr>
+</listener>
+
+<listener event="firstSearcher" class="solr.QuerySenderListener">
+ <arr name="queries">
+ <lst><str name="q">static firstSearcher warming in solrconfig.xml</str></lst>
+ </arr>
+</listener>
+----
+
+[IMPORTANT]
+====
+The above code comes from a _sample_ `solrconfig.xml`.
+
+A key best practice is to modify these defaults before taking your application to production, but please note: while the sample queries are commented out in the section for the "newSearcher", the sample query is not commented out for the "firstSearcher" event.
+
+There is no point in auto-warming your Searcher with the query string "static firstSearcher warming in solrconfig.xml" if that is not relevant to your search application.
+====
diff --git a/solr/solr-ref-guide/src/cluster-plugins.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/cluster-plugins.adoc
similarity index 100%
rename from solr/solr-ref-guide/src/cluster-plugins.adoc
rename to solr/solr-ref-guide/modules/configuration-guide/pages/cluster-plugins.adoc
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/codec-factory.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/codec-factory.adoc
new file mode 100644
index 0000000..c16b59b
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/codec-factory.adoc
@@ -0,0 +1,58 @@
+= Codec Factory
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+A `codecFactory` can be specified in `solrconfig.xml` to determine which Lucene {lucene-javadocs}/core/org/apache/lucene/codecs/Codec.html[`Codec`] is used when writing the index to disk.
+
+If not specified, Lucene's default codec is implicitly used.
+
+== Alternatives to the Default Codec
+There are two alternatives to Lucene's default codec.
+
+=== solr.SchemaCodecFactory
+
+The {solr-javadocs}/core/org/apache/solr/core/SchemaCodecFactory.html[`solr.SchemaCodecFactory`] supports 2 key features:
+
+* Schema based per-fieldtype configuration for `docValuesFormat` and `postingsFormat` - see the xref:indexing-guide:field-type-definitions-and-properties.adoc#field-type-properties[Field Type Properties] section for more details.
+* A `compressionMode` option:
+** `BEST_SPEED` (default) is optimized for search speed performance
+** `BEST_COMPRESSION` is optimized for disk space usage
+
+Example:
+
+[source,xml]
+----
+<codecFactory class="solr.SchemaCodecFactory">
+ <str name="compressionMode">BEST_COMPRESSION</str>
+</codecFactory>
+----
+
+=== solr.SimpleTextCodecFactory
+
+This factory for Lucene's {solr-javadocs}/core/org/apache/solr/core/SimpleTextCodecFactory.html[`SimpleTextCodecFactory`] produces a plain text human-readable index format.
+
+CAUTION: *FOR RECREATIONAL USE ONLY*.
+This codec should never be used in production.
+`SimpleTextCodec` is relatively slow and takes up a large amount of disk space.
+Its use should be limited to educational and debugging purposes.
+
+Example:
+
+[source,xml]
+----
+<codecFactory class="solr.SimpleTextCodecFactory"/>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc
new file mode 100644
index 0000000..5995546
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/collections-api.adoc
@@ -0,0 +1,303 @@
+= Collections API
+:page-show-toc: false
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+A SolrCloud cluster includes a number of components.
+The Collections API is provided to allow you to control your cluster, including the collections, shards, replicas, backups, leader election, and other operations needs.
+
+Because this API has a large number of commands and options, we've grouped the commands into the following sub-sections:
+
+*xref:deployment-guide:cluster-node-management.adoc[]*: Define properties for the entire cluster; check the status of a cluster; remove replicas from a node; utilize a newly added node; add or remove roles for a node.
+
+*xref:deployment-guide:collection-management.adoc[]*: Create, list, reload and delete collections; set collection properties; migrate documents to another collection; rebalance leaders; backup and restore collections.
+
+*xref:deployment-guide:alias-management.adoc[]*: Create, list or delete collection aliases; set alias properties.
+
+*xref:deployment-guide:shard-management.adoc[]*: Create and delete a shard; split a shard into two or more additional shards; force a shard leader.
+
+*xref:deployment-guide:replica-management.adoc[]*: Add or delete a replica; set replica properties; move a replica to a different node.
+
+== Asynchronous Calls
+
+Since some collection API calls can be long running tasks (such as SPLITSHARD), you can optionally have the calls run asynchronously.
+Specifying `async=<request-id>` enables you to make an asynchronous call, the status of which can be requested using the <<requeststatus,REQUESTSTATUS>> call at any time.
+
+As of now, REQUESTSTATUS does not automatically clean up the tracking data structures, meaning the status of completed or failed tasks stays stored in ZooKeeper unless cleared manually.
+DELETESTATUS can be used to clear the stored statuses.
+However, there is a limit of 10,000 on the number of async call responses stored in a cluster.
+
+=== Examples of Async Requests
+
+*Input*
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1asyncexample]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=collection1&shard=shard1&async=1000
+
+----
+====
+
+[example.tab-pane#v2asyncexample]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/api/collections/collection1/shards -H 'Content-Type: application/json' -d '
+ {
+ "split": {
+ "shard": "shard1",
+ "async": "1000"
+ }
+ }
+'
+----
+====
+--
+
+
+[source,text]
+----
+
+----
+
+*Output*
+
+[source,json]
+----
+{
+ "responseHeader":{
+ "status":0,
+ "QTime":115},
+ "requestid":"1000"}
+----
+
+
+[[requeststatus]]
+== REQUESTSTATUS: Request Status of an Async Call
+
+Request the status and response of an already submitted <<Asynchronous Calls,Asynchronous Collection API>> (below) call.
+This call is also used to clear up the stored statuses.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1asyncrequeststatus]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000
+
+----
+====
+
+[example.tab-pane#v2asyncrequeststatus]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X GET http://localhost:8983/api/cluster/command-status/1000
+----
+====
+--
+
+=== REQUESTSTATUS Parameters
+
+`requestid`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The user defined request ID for the request.
+This can be used to track the status of the submitted asynchronous task.
+
+=== Examples using REQUESTSTATUS
+
+*Input: Valid Request ID*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000&wt=xml
+----
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">1</int>
+ </lst>
+ <lst name="status">
+ <str name="state">completed</str>
+ <str name="msg">found 1000 in completed tasks</str>
+ </lst>
+</response>
+----
+
+*Input: Invalid Request ID*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1004&wt=xml
+----
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">1</int>
+ </lst>
+ <lst name="status">
+ <str name="state">notfound</str>
+ <str name="msg">Did not find taskid [1004] in any tasks queue</str>
+ </lst>
+</response>
+----
+
+[[deletestatus]]
+== DELETESTATUS: Delete Status
+
+Deletes the stored response of an already failed or completed <<Asynchronous Calls,Asynchronous Collection API>> call.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1asyncdeletestatus]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=1000
+
+----
+====
+
+[example.tab-pane#v2asyncdeletestatus]
+====
+[.tab-label]*V2 API*
+
+Delete a single request response:
+[source,bash]
+----
+curl -X DELETE http://localhost:8983/api/cluster/command-status/1000
+----
+
+Flush out all stored completed and failed async request responses:
+[source,bash]
+----
+curl -X DELETE http://localhost:8983/api/cluster/command-status?flush=true
+----
+====
+--
+
+=== DELETESTATUS Parameters
+
+`requestid`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The request ID of the asynchronous call whose stored response should be cleared.
+
+`flush`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Set to `true` to clear all stored completed and failed async request responses.
+
+=== Examples using DELETESTATUS
+
+*Input: Valid Request ID*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=foo&wt=xml
+----
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">1</int>
+ </lst>
+ <str name="status">successfully removed stored response for [foo]</str>
+</response>
+----
+
+*Input: Invalid Request ID*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=bar&wt=xml
+----
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">1</int>
+ </lst>
+ <str name="status">[bar] not found in stored responses</str>
+</response>
+----
+
+*Input: Clear All Stored Statuses*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=DELETESTATUS&flush=true&wt=xml
+----
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">1</int>
+ </lst>
+ <str name="status"> successfully cleared stored collection api responses </str>
+</response>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/commits-transaction-logs.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/commits-transaction-logs.adoc
new file mode 100644
index 0000000..da25bfc
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/commits-transaction-logs.adoc
@@ -0,0 +1,322 @@
+= Commits and Transaction Logs
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+In Solr, documents are not available for searching until a "commit" updates the Lucene index files.
+Your commit strategy will determine when document additions, deletes, or changes are available for searching.
+A transaction log records document updates that have been received since the last "hard" commit point.
+
+== <updateHandler> in solrconfig.xml
+
+The settings in this section are configured in the `<updateHandler>` element in `solrconfig.xml` and may affect the performance of index updates.
+These settings affect how updates are done internally.
+
+The `<updateHandler>` element takes a class parameter, which must be `solr.DirectUpdateHandler2`.
+The `_default` configset included with Solr has this section defined already, but the values for many parameters discussed below likely need to be customized for your application.
+
+[source,xml]
+----
+<config>
+ <updateHandler class="solr.DirectUpdateHandler2">
+ ...
+ </updateHandler>
+</config>
+----
+
+Note that `<updateHandler>` configurations do not affect the higher level configuration of xref:requesthandlers-searchcomponents.adoc[request handlers] that process client update requests.
+
+== Commits
+
+Data sent to Solr is not searchable until it has been _committed_ to the index.
+The reason for this is that in some cases commits can be slow and they should be done in isolation from other possible commit requests to avoid overwriting data.
+
+=== Hard Commits vs. Soft Commits
+
+Solr supports two types of commits: hard commits and soft commits.
+
+A *hard commit* calls `fsync` on the index files to ensure they have been flushed to stable storage.
+The current transaction log is closed and a new one is opened.
+See the section <<Transaction Log>> below for how data is recovered in the absence of a hard commit.
+Optionally a hard commit can also make documents visible for search, but this may not be ideal in some use cases as it is more expensive than a soft commit.
+By default commit actions result in a hard commit of all the Lucene index files to stable storage (disk).
+
+A *soft commit* is faster since it only makes index changes visible and does not `fsync` index files, start a new segment, nor start a new transaction log.
+Search collections that have NRT requirements will want to soft commit often enough to satisfy the visibility requirements of the application.
+A softCommit may be "less expensive" than a hard commit (`openSearcher=true`), but it is not free.
+It is recommended that this be set for as long as is reasonable given the application requirements.
+
+A hard commit means that, if a server crashes, Solr will know exactly where your data was stored; a soft commit means that the data is stored, but the location information isn't yet stored.
+The tradeoff is that a soft commit gives you faster visibility because it's not waiting for background merges to finish.
+
+=== Explicit Commits
+
+When a client includes a `commit=true` parameter with an update request, this ensures that all index segments affected by the adds and deletes on an update are written to disk as soon as index updates are completed.
+
+If an additional parameter `softCommit=true` is specified, then Solr performs a soft commit.
+This is an implementation of Near Real Time storage, a feature that boosts document visibility, since you don't have to wait for background merges and storage (to ZooKeeper, if using SolrCloud) to finish before moving on to something else.
+
+Details about using explicit commit requests during indexing are in the section xref:indexing-guide:indexing-with-update-handlers.adoc[Indexing with Update Handlers].
+
+For more information about Near Real Time operations, see xref:deployment-guide:solrcloud-distributed-requests.adoc#near-real-time-nrt-use-cases[Near Real Time Use Cases].
+
+=== Automatic Commits
+
+To avoid sending explicit commit commands during indexing and to provide control over when commits happen, it's possible to configure `autoCommit` parameters in `solrconfig.xml`.
+
+This is preferable to sending explicit commits from the indexing client as it offers much more control over your commit strategy.
+Note that defaults are provided in `solrconfig.xml`, but they are very likely not tuned to your needs and may introduce performance problems if not tuned effectively.
+
+These settings control how often pending updates will be automatically pushed to the index.
+
+`maxDocs`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The number of updates that have occurred since the last commit.
+
+`maxTime`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The number of milliseconds since the oldest uncommitted update.
+When sending a large batch of documents, this parameter is preferred over `maxDocs`.
+
+`maxSize`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum size of the transaction log (tlog) on disk, after which a hard commit is triggered.
+This is useful when the size of documents is unknown and the intention is to restrict the size of the transaction log to reasonable size.
++
+Valid values can be bytes (default with no suffix), kilobytes (if defined with a `k` suffix, as in `25k`), megabytes (`m`) or gigabytes (`g`).
+
+`openSearcher`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+Whether to open a new searcher when performing a commit.
+If this is `false`, the commit will flush recent index changes to stable storage, but does not cause a new searcher to be opened to make those changes visible.
+
+If any of the `maxDocs`, `maxTime`, or `maxSize` limits are reached, Solr automatically performs a commit operation.
+The first of these thresholds to be reached will trigger the commit.
+
+If the `autoCommit` tag is missing from `solrconfig.xml`, then only explicit commits will update the index.
+The decision whether to use autoCommit or not depends on the needs of your application.
+
+[source,xml]
+----
+<autoCommit>
+ <maxDocs>10000</maxDocs>
+ <maxTime>30000</maxTime>
+ <maxSize>512m</maxSize>
+ <openSearcher>false</openSearcher>
+</autoCommit>
+----
+
+You can also specify 'soft' autoCommits with the `autoSoftCommit` tag.
+
+[source,xml]
+----
+<autoSoftCommit>
+ <maxTime>60000</maxTime>
+</autoSoftCommit>
+----
+
+=== AutoCommit Best Practices
+
+Determining the best `autoCommit` settings is a tradeoff between performance and accuracy.
+Settings that cause frequent updates will improve the accuracy of searches because new content will be searchable more quickly, but performance may suffer because of the frequent updates.
+Less frequent updates may improve performance but it will take longer for updates to show up in queries.
+
+Here is an example NRT configuration for the two flavors of commit, a hard commit every 60 seconds and a soft commit every 30 seconds.
+Note that these are _not_ the values in the examples shipped with Solr!
+
+[source,xml]
+----
+<autoCommit>
+ <maxTime>${solr.autoCommit.maxTime:60000}</maxTime>
+ <openSearcher>false</openSearcher>
+</autoCommit>
+
+<autoSoftCommit>
+ <maxTime>${solr.autoSoftCommit.maxTime:30000}</maxTime>
+ </autoSoftCommit>
+----
+
+TIP: These parameters can be overridden at run time by defining Java "system variables", for example specifying ``-Dsolr.autoCommit.maxTime=15000` would override the hard commit interval with a value of 15 seconds.
+
+The choices for `autoCommit` (with `openSearcher=false`) and `autoSoftCommit` have different consequences.
+In the event of un-graceful shutdown, it can take up to the time specified in `autoCommit` for Solr to replay the uncommitted documents from the transaction log.
+
+The time chosen for `autoSoftCommit` determines the maximum time after a document is sent to Solr before it becomes searchable and does not affect the transaction log.
+
+Choose as long an interval as your application can tolerate for this value, often 15-60 seconds is reasonable, or even longer depending on the requirements.
+In situations where the time is set to a very short interval (say 1 second), consider disabling your caches (queryResultCache and filterCache especially) as they will have little utility.
+
+TIP: For extremely high bulk indexing, especially for the initial load if there is no searching, consider turning off `autoSoftCommit` by specifying a value of `-1` for the maxTime parameter.
+
+=== Commit Within a Time Period
+
+An alternative to `autoCommit` is to use `commitWithin`, which can be defined when making the update request to Solr (i.e., when pushing documents), or in an update request handler.
+
+The `commitWithin` settings allow forcing document commits to happen in a defined time period.
+This is used most frequently with xref:deployment-guide:solrcloud-distributed-requests.adoc#near-real-time-nrt-use-cases[Near Real Time use cases], and for that reason the default is to perform a soft commit.
+This does not, however, replicate new documents to follower servers in a user-managed cluster.
+If that's a requirement for your implementation, you can force a hard commit by adding a parameter, as in this example:
+
+[source,xml]
+----
+<commitWithin>
+ <softCommit>false</softCommit>
+</commitWithin>
+----
+
+With this configuration, when you call `commitWithin` as part of your update message, it will automatically perform a hard commit every time.
+
+
+== Transaction Log
+
+Transaction logs (tlogs) are a "rolling window" of updates since the last hard commit.
+The current transaction log is closed and a new one opened each time any variety of hard commit occurs.
+Soft commits have no effect on the transaction log.
+
+When tlogs are enabled, documents being added to the index are written to the tlog before the indexing call returns to the client.
+In the event of an un-graceful shutdown (power loss, JVM crash, `kill -9`, etc.) any documents written to the tlog but not yet committed with a hard commit when Solr was stopped are replayed on startup.
+Therefore the data is not lost.
+
+When Solr is shut down gracefully (using the `bin/solr stop` command) Solr will close the tlog file and index segments so no replay will be necessary on startup.
+
+One point of confusion is how much data is contained in a transaction log.
+A tlog does not contain all documents, only the ones since the last hard commit.
+Older transaction log files are deleted when no longer needed.
+
+WARNING: Implicit in the above is that transaction logs will grow forever if hard commits are disabled.
+Therefore it is important that hard commits be enabled when indexing.
+
+=== Transaction Log Configuration
+
+Transaction logs are required for all SolrCloud clusters, as well as the xref:realtime-get.adoc[] feature.
+It is configured in the `updateHandler` section of `solrconfig.xml`.
+
+Transaction logs are configured in `solrconfig.xml`, in a section like the following:
+
+[source,xml]
+----
+<updateLog>
+ <str name="dir">${solr.ulog.dir:}</str>
+</updateLog>
+----
+
+The only required parameter is:
+
+`dir`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The location of the transaction log.
+In Solr's default `solrconfig.xml` files, this is defined as `${solr.ulog.dir:}`.
++
+As shown in the default value, the location of the transaction log can be anywhere as long as it is defined in `solrconfig.xml` and write- and read-able by Solr.
+
+There are three additional expert-level configuration settings which affect indexing performance and how far a replica can fall behind on updates before it must enter into full recovery.
+These settings would primarily impact SolrCloud cluster configurations:
+
+`numRecordsToKeep`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `100`
+|===
++
+The minimum number of update records to keep across all the transaction log files.
+
+`maxNumLogsToKeep`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `10`
+|===
++
+The maximum number of transaction log files to keep.
+
+`numVersionBuckets`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `65336`
+|===
++
+The number of buckets used to keep track of maximum version values when checking for re-ordered updates.
+Increase this value to reduce the cost of synchronizing access to version buckets during high-volume indexing.
+This requires `(8 bytes (long) * numVersionBuckets)` of heap space per Solr core.
+
+An example, to be included under `<updateHandler>` in `solrconfig.xml`, employing the above advanced settings:
+
+[source,xml]
+----
+<updateLog>
+ <str name="dir">${solr.ulog.dir:}</str>
+ <int name="numRecordsToKeep">500</int>
+ <int name="maxNumLogsToKeep">20</int>
+ <int name="numVersionBuckets">65536</int>
+</updateLog>
+----
+
+== Event Listeners
+
+The UpdateHandler section is also where update-related event listeners can be configured.
+These can be triggered to occur after any commit (`event="postCommit"`) or only after optimize commands (`event="postOptimize"`).
+
+Users can write custom update event listener classes in Solr plugins.
+As of Solr 7.1, `RunExecutableListener` was removed for security reasons.
+
+== Other <updateHandler> Options
+
+In some cases complex updates (such as spatial/shape) may take very long time to complete.
+In the default configuration other updates that fall into the same internal version bucket will wait indefinitely.
+Eventually these outstanding requests may pile up and lead to thread exhaustion and possibly to OutOfMemory errors.
+
+The parameter `versionBucketLockTimeoutMs` helps to prevent that by specifying a timeout for long-running update requests.
+If this limit is reached the update will fail but it won't block forever all other updates.
+
+There is a memory cost associated with this setting.
+Values greater than the default of `0` (unlimited timeout) cause Solr to use a different internal implementation of the version bucket, which increases memory consumption from ~1.5MB to ~6.8MB per Solr core.
+
+An example of specifying this option under `<config>` section of `solrconfig.xml`:
+
+[source,xml]
+----
+<updateHandler class="solr.DirectUpdateHandler2">
+ ...
+ <int name="versionBucketLockTimeoutMs">10000</int>
+</updateHandler>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/config-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/config-api.adoc
new file mode 100644
index 0000000..c9e2f90
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/config-api.adoc
@@ -0,0 +1,933 @@
+= Config API
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Config API enables manipulating various aspects of your `solrconfig.xml` using REST-like API calls.
+
+This feature is enabled by default and works similarly in both SolrCloud, user-managed clusters, and single-node installations.
+Many commonly edited properties (such as cache sizes and commit settings) and request handler definitions can be changed with this API.
+
+When using this API, `solrconfig.xml` is not changed.
+Instead, all edited configuration is stored in a file called `configoverlay.json`.
+The values in `configoverlay.json` override the values in `solrconfig.xml`.
+
+== Config API Endpoints
+
+All Config API endpoints are collection-specific, meaning this API can inspect or modify the configuration for a single collection at a time.
+
+* `_collection_/config`: retrieve the full effective config, or modify the config.
+Use GET to retrieve and POST for executing commands.
+* `_collection_/config/overlay`: retrieve the details in the `configoverlay.json` only, removing any options defined in `solrconfig.xml` directly or implicitly through defaults.
+* `_collection_/config/params`: create parameter sets that can override or take the place of parameters defined in `solrconfig.xml`.
+See xref:request-parameters-api.adoc[] for more information about this endpoint.
+
+== Retrieving the Config
+
+All configuration items can be retrieved by sending a GET request to the `/config` endpoint:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1getconfig]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2getconfig]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+The response will be the Solr configuration resulting from merging settings in `configoverlay.json` with those in `solrconfig.xml`.
+
+
+It's possible to restrict the returned configuration to a top-level section, such as, `query`, `requestHandler` or `updateHandler`.
+To do this, append the name of the section to the `config` endpoint.
+For example, to retrieve configuration for all request handlers:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1gethandler]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/config/requestHandler
+----
+====
+
+[example.tab-pane#v2gethandler]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/config/requestHandler
+----
+====
+--
+
+The output will be details of each request handler defined in `solrconfig.xml`, xref:implicit-requesthandlers.adoc[defined implicitly] by Solr, and defined with this Config API stored in `configoverlay.json`.
+To see the configuration for implicit request handlers, add `expandParams=true` to the request.
+See the documentation for implicit request handlers linked above for examples using this command.
+
+The available top-level sections that can be added as path parameters are: `query`, `requestHandler`, `searchComponent`, `updateHandler`, `queryResponseWriter`, `initParams`, `znodeVersion`, `listener`, `directoryFactory`, `indexConfig`, and `codecFactory`.
+
+To further restrict the request to a single component within a top-level section, use the `componentName` request parameter.
+
+For example, to return configuration for the `/select` request handler:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1getcomponent]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/config/requestHandler?componentName=/select
+----
+====
+
+[example.tab-pane#v2getcomponent]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/config/requestHandler?componentName=/select
+----
+====
+--
+
+The output of this command will look similar to:
+
+[source,json]
+----
+{
+ "config":{"requestHandler":{"/select":{
+ "name": "/select",
+ "class": "solr.SearchHandler",
+ "defaults":{
+ "echoParams": "explicit",
+ "rows":10
+ }}}}
+}
+----
+
+The ability to restrict to objects within a top-level section is limited to request handlers (`requestHandler`), search components (`searchComponent`), and response writers (`queryResponseWriter`).
+
+== Commands to Modify the Config
+
+This API uses specific commands with POST requests to tell Solr what property or type of property to add to or modify in `configoverlay.json`.
+The commands are passed with the data to add or modify the property or component.
+
+The Config API commands for modifications are categorized into 3 types, each of which manipulate specific data structures in `solrconfig.xml`.
+These types are:
+
+* `set-property` and `unset-property` for <<Commands for Common Properties,Common Properties>>
+* Component-specific `add-`, `update-`, and `delete-` commands for <<Commands for Handlers and Components,Custom Handlers and Local Components>>
+* `set-user-property` and `unset-user-property` for <<Commands for User-Defined Properties,User-defined properties>>
+
+=== Commands for Common Properties
+
+The common properties are those that are frequently customized in a Solr instance.
+They are manipulated with two commands:
+
+* `set-property`: Set a known property.
+The names of the properties are predefined and fixed.
+If the property has already been set, this command will overwrite the previous setting.
+* `unset-property`: Remove a property set using the `set-property` command.
+
+The properties that can be configured with `set-property` and `unset-property` are predefined and listed below.
+The names of these properties are derived from their XML paths as found in `solrconfig.xml`.
+
+*Update Handler Settings*
+
+See xref:commits-transaction-logs.adoc[] for defaults and acceptable values for these settings.
+
+* `updateHandler.autoCommit.maxDocs`
+* `updateHandler.autoCommit.maxTime`
+* `updateHandler.autoCommit.openSearcher`
+* `updateHandler.autoSoftCommit.maxDocs`
+* `updateHandler.autoSoftCommit.maxTime`
+* `updateHandler.commitWithin.softCommit`
+
+*Query Settings*
+
+See xref:caches-warming.adoc[] for defaults and acceptable values for these settings.
+
+_Caches and Cache Sizes_
+
+* `query.filterCache.class`
+* `query.filterCache.size`
+* `query.filterCache.initialSize`
+* `query.filterCache.autowarmCount`
+* `query.filterCache.maxRamMB`
+* `query.filterCache.regenerator`
+* `query.queryResultCache.class`
+* `query.queryResultCache.size`
+* `query.queryResultCache.initialSize`
+* `query.queryResultCache.autowarmCount`
+* `query.queryResultCache.maxRamMB`
+* `query.queryResultCache.regenerator`
+* `query.documentCache.class`
+* `query.documentCache.size`
+* `query.documentCache.initialSize`
+* `query.documentCache.autowarmCount`
+* `query.documentCache.regenerator`
+* `query.fieldValueCache.class`
+* `query.fieldValueCache.size`
+* `query.fieldValueCache.initialSize`
+* `query.fieldValueCache.autowarmCount`
+* `query.fieldValueCache.regenerator`
+
+_Query Sizing and Warming_
+
+* `query.maxBooleanClauses`
+* `query.enableLazyFieldLoading`
+* `query.useFilterForSortedQuery`
+* `query.queryResultWindowSize`
+* `query.queryResultMaxDocCached`
+
+_Query Circuit Breakers_
+
+See xref:deployment-guide:circuit-breakers.adoc[] for more details
+
+* `query.useCircuitBreakers`
+* `query.memoryCircuitBreakerThresholdPct`
+
+*RequestDispatcher Settings*
+
+See xref:requestdispatcher.adoc[] for defaults and acceptable values for these settings.
+
+* `requestDispatcher.handleSelect`
+* `requestDispatcher.requestParsers.enableRemoteStreaming`
+* `requestDispatcher.requestParsers.enableStreamBody`
+* `requestDispatcher.requestParsers.multipartUploadLimitInKB`
+* `requestDispatcher.requestParsers.formdataUploadLimitInKB`
+* `requestDispatcher.requestParsers.addHttpRequestToContext`
+
+==== Examples of Common Properties
+
+Constructing a command to modify or add one of these properties follows this pattern:
+
+[source,json,subs="quotes"]
+----
+{"set-property":{"<_property_>": "<_value_>"}}
+----
+
+A request to increase the `updateHandler.autoCommit.maxTime` would look like:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1-setprop]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2-setprop]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+You can use the `config/overlay` endpoint to verify the property has been added to `configoverlay.json`:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1overlay]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/overlay?omitHeader=true
+----
+====
+
+[example.tab-pane#v2overlay]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl http://localhost:8983/api/collections/techproducts/config/overlay?omitHeader=true
+----
+====
+--
+
+Output:
+
+[source,json]
+----
+{
+ "overlay": {
+ "znodeVersion": 1,
+ "props": {
+ "updateHandler": {
+ "autoCommit": {"maxTime": 15000}
+ }
+}}}
+----
+
+To unset the property:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1unsetprop]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2unsetprop]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+=== Commands for Handlers and Components
+
+Request handlers, search components, and other types of localized Solr components (such as query parsers, update processors, etc.) can be added, updated and deleted with specific commands for the type of component being modified.
+
+The syntax is similar in each case: `add-<_component-name_>`, `update-<_component-name_>`, and `delete-<_component-name_>`.
+The command name is not case sensitive, so `Add-RequestHandler`, `ADD-REQUESTHANDLER` and `add-requesthandler` are equivalent.
+
+In each case, `add-` commands add a new configuration to `configoverlay.json`, which will override any other settings for the component in `solrconfig.xml`.
+
+`update-` commands overwrite an existing setting in `configoverlay.json`.
+
+`delete-` commands remove the setting from `configoverlay.json`.
+
+Settings removed from `configoverlay.json` are not removed from `solrconfig.xml` if they happen to be duplicated there.
+
+The full list of available commands follows below:
+
+==== Basic Commands for Components
+
+These commands are the most commonly used:
+
+* `add-requesthandler`
+* `update-requesthandler`
+* `delete-requesthandler`
+* `add-searchcomponent`
+* `update-searchcomponent`
+* `delete-searchcomponent`
+* `add-initparams`
+* `update-initparams`
+* `delete-initparams`
+* `add-queryresponsewriter`
+* `update-queryresponsewriter`
+* `delete-queryresponsewriter`
+
+==== Advanced Commands for Components
+
+These commands allow registering more advanced customizations to Solr:
+
+* `add-queryparser`
+* `update-queryparser`
+* `delete-queryparser`
+* `add-valuesourceparser`
+* `update-valuesourceparser`
+* `delete-valuesourceparser`
+* `add-transformer`
+* `update-transformer`
+* `delete-transformer`
+* `add-updateprocessor`
+* `update-updateprocessor`
+* `delete-updateprocessor`
+* `add-queryconverter`
+* `update-queryconverter`
+* `delete-queryconverter`
+* `add-listener`
+* `update-listener`
+* `delete-listener`
+* `add-expressible`
+* `update-expressible`
+* `delete-expressible`
+
+==== Examples of Handler and Component Commands
+
+To create a request handler, we can use the `add-requesthandler` command:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "add-requesthandler": {
+ "name": "/mypath",
+ "class": "solr.DumpRequestHandler",
+ "defaults":{ "x": "y" ,"a": "b", "rows":10 },
+ "useParams": "x"
+ }
+}' http://localhost:8983/solr/techproducts/config
+----
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1addhandler]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "add-requesthandler": {
+ "name": "/mypath",
+ "class": "solr.DumpRequestHandler",
+ "defaults": { "x": "y" ,"a": "b", "rows":10 },
+ "useParams": "x"
+ }
+}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2addhandler]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "add-requesthandler": {
+ "name": "/mypath",
+ "class": "solr.DumpRequestHandler",
+ "defaults": { "x": "y" ,"a": "b", "rows":10 },
+ "useParams": "x"
+ }
+}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+Make a call to the new request handler to check if it is registered:
+
+[source,bash]
+----
+$ curl http://localhost:8983/solr/techproducts/mypath?omitHeader=true
+----
+
+And you should see the following as output:
+
+[source,json]
+----
+{
+ "params":{
+ "indent": "true",
+ "a": "b",
+ "x": "y",
+ "rows": "10"},
+ "context":{
+ "webapp": "/solr",
+ "path": "/mypath",
+ "httpMethod": "GET"}}
+----
+
+To update a request handler, you should use the `update-requesthandler` command:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1updatehandler]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "update-requesthandler": {
+ "name": "/mypath",
+ "class": "solr.DumpRequestHandler",
+ "defaults": {"x": "new value for X", "rows": "20"},
+ "useParams": "x"
+ }
+}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2updatehandler]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "update-requesthandler": {
+ "name": "/mypath",
+ "class": "solr.DumpRequestHandler",
+ "defaults": {"x": "new value for X", "rows": "20"},
+ "useParams": "x"
+ }
+}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+As a second example, we'll create another request handler, this time adding the 'terms' component as part of the definition:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1add-handler]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "add-requesthandler": {
+ "name": "/myterms",
+ "class": "solr.SearchHandler",
+ "defaults": {"terms": true, "distrib":false},
+ "components": ["terms"]
+ }
+}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2add-handler]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "add-requesthandler": {
+ "name": "/myterms",
+ "class": "solr.SearchHandler",
+ "defaults": {"terms": true, "distrib":false},
+ "components": ["terms"]
+ }
+}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+Finally we will go ahead and remove the request handler via the `delete-requesthandler` command:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1delete-handler]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "delete-requesthandler": "/myterms"
+}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2delete-handler]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{
+ "delete-requesthandler": "/myterms"
+}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+=== Commands for User-Defined Properties
+
+Solr lets users templatize the `solrconfig.xml` using the place holder format `${variable_name:default_val}`.
+You could set the values using system properties, for example, `-Dvariable_name= my_customvalue`.
+The same can be achieved during runtime using these commands:
+
+* `set-user-property`: Set a user-defined property.
+If the property has already been set, this command will overwrite the previous setting.
+* `unset-user-property`: Remove a user-defined property.
+
+The structure of the request is similar to the structure of requests using other commands, in the format of `"command":{"variable_name": "property_value"}`.
+You can add more than one variable at a time if necessary.
+
+For more information about user-defined properties, see the section xref:property-substitution.adoc#user-defined-properties-in-core-properties[User defined properties in core.properties].
+
+See also the section <<Creating and Updating User-Defined Properties>> below for examples of how to use this type of command.
+
+==== Creating and Updating User-Defined Properties
+
+This command sets a user property.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1userprop]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2userprop]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+Again, we can use the `/config/overlay` endpoint to verify the changes have been made:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1useroverlay]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/overlay?omitHeader=true
+----
+====
+
+[example.tab-pane#v2useroverlay]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl http://localhost:8983/api/collections/techproducts/config/overlay?omitHeader=true
+----
+====
+--
+
+And we would expect to see output like this:
+
+[source,json]
+----
+{"overlay":{
+ "znodeVersion":5,
+ "userProps":{
+ "variable_name": "some_value"}}
+}
+----
+
+To unset the variable, issue a command like this:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1unsetuser]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2unsetuser]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+=== updateRequestProcessorChain Elements
+
+The Config API does not let you create or edit `updateRequestProcessorChain` elements.
+However, it is possible to create `updateProcessor` entries and use them by name to create a chain.
+
+For example:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1addupdateproc]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
+ {"name": "firstFld",
+ "class": "solr.FirstFieldValueUpdateProcessorFactory",
+ "fieldName": "test_s"}
+}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2addupdateproc]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
+ {"name": "firstFld",
+ "class": "solr.FirstFieldValueUpdateProcessorFactory",
+ "fieldName": "test_s"}
+}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+You can use this directly in your request by adding a parameter in the `updateRequestProcessorChain` for the specific update processor called `processor=firstFld`.
+
+== How to Map solrconfig.xml Properties to JSON
+
+By using this API, you will be generating JSON representations of properties defined in `solrconfig.xml`.
+To understand how properties should be represented with the API, let's take a look at a few examples.
+
+Here is what a request handler looks like in `solrconfig.xml`:
+
+[source,xml]
+----
+<requestHandler name="/query" class="solr.SearchHandler">
+ <lst name="defaults">
+ <str name="echoParams">explicit</str>
+ <int name="rows">10</str>
+ </lst>
+</requestHandler>
+----
+
+The same request handler defined with the Config API would look like this:
+
+[source,json]
+----
+{
+ "add-requesthandler":{
+ "name": "/query",
+ "class": "solr.SearchHandler",
+ "defaults":{
+ "echoParams": "explicit",
+ "rows": 10
+ }
+ }
+}
+----
+
+The QueryElevationComponent searchComponent in `solrconfig.xml` looks like this:
+
+[source,xml]
+----
+<searchComponent name="elevator" class="solr.QueryElevationComponent" >
+ <str name="queryFieldType">string</str>
+ <str name="config-file">elevate.xml</str>
+</searchComponent>
+----
+
+And the same searchComponent with the Config API:
+
+[source,json]
+----
+{
+ "add-searchcomponent":{
+ "name": "elevator",
+ "class": "solr.QueryElevationComponent",
+ "queryFieldType": "string",
+ "config-file": "elevate.xml"
+ }
+}
+----
+
+Removing the searchComponent with the Config API:
+
+[source,json]
+----
+{
+ "delete-searchcomponent": "elevator"
+}
+----
+
+A simple highlighter looks like this in `solrconfig.xml` (example has been truncated for space):
+
+[source,xml]
+----
+<searchComponent class="solr.HighlightComponent" name="highlight">
+ <highlighting>
+ <fragmenter name="gap"
+ default="true"
+ class="solr.highlight.GapFragmenter">
+ <lst name="defaults">
+ <int name="hl.fragsize">100</int>
+ </lst>
+ </fragmenter>
+
+ <formatter name="html"
+ default="true"
+ class="solr.highlight.HtmlFormatter">
+ <lst name="defaults">
+ <str name="hl.simple.pre"><![CDATA[<em>]]></str>
+ <str name="hl.simple.post"><![CDATA[</em>]]></str>
+ </lst>
+ </formatter>
+
+ <encoder name="html" class="solr.highlight.HtmlEncoder" />
+...
+ </highlighting>
+----
+
+The same highlighter with the Config API:
+
+[source,json]
+----
+{
+ "add-searchcomponent": {
+ "name": "highlight",
+ "class": "solr.HighlightComponent",
+ "": {
+ "gap": {
+ "default": "true",
+ "name": "gap",
+ "class": "solr.highlight.GapFragmenter",
+ "defaults": {
+ "hl.fragsize": 100
+ }
+ }
+ },
+ "html": [{
+ "default": "true",
+ "name": "html",
+ "class": "solr.highlight.HtmlFormatter",
+ "defaults": {
+ "hl.simple.pre": "before-",
+ "hl.simple.post": "-after"
+ }
+ }, {
+ "name": "html",
+ "class": "solr.highlight.HtmlEncoder"
+ }]
+ }
+}
+----
+
+Set autoCommit properties in `solrconfig.xml`:
+
+[source,xml]
+----
+<autoCommit>
+ <maxTime>15000</maxTime>
+ <openSearcher>false</openSearcher>
+</autoCommit>
+----
+
+Define the same properties with the Config API:
+
+[source,json]
+----
+{
+ "set-property": {
+ "updateHandler.autoCommit.maxTime":15000,
+ "updateHandler.autoCommit.openSearcher":false
+ }
+}
+----
+
+=== Name Components for the Config API
+
+The Config API always allows changing the configuration of any component by name.
+However, some configurations such as `listener` or `initParams` do not require a name in `solrconfig.xml`.
+In order to be able to `update` and `delete` of the same item in `configoverlay.json`, the name attribute becomes mandatory.
+
+
+== How the Config API Works
+
+When using SolrCloud, every core watches the ZooKeeper directory for the configset being used with that core.
+If there are multiple cores in the same node using the same configset, only one ZooKeeper watch is used.
+
+TIP:: In a user-managed cluster or single-node installation, there is no watch (because ZooKeeper is not running).
+
+For instance, if the configset 'myconf' is used by a core, the node would watch `/configs/myconf`.
+Every write operation performed through the API would 'touch' the directory and all watchers are notified.
+Every core would check if the schema file, `solrconfig.xml`, or `configoverlay.json` has been modified by comparing the `znode` versions.
+If any have been modified, the core is reloaded.
+
+If `params.json` is modified, the params object is just updated without a core reload (see xref:request-parameters-api.adoc[] for more information about `params.json`).
+
+=== Empty Command
+
+If an empty command is sent to the `/config` endpoint, the watch is triggered on all cores using this configset.
+For example:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1empty]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{}' http://localhost:8983/solr/techproducts/config
+----
+====
+
+[example.tab-pane#v2empty]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' -d '{}' http://localhost:8983/api/collections/techproducts/config
+----
+====
+--
+
+Directly editing any files without 'touching' the directory *will not* make it visible to all nodes.
+
+It is possible for components to watch for the configset 'touch' events by registering a listener using `SolrCore#registerConfListener()`.
+
+=== Listening to Config Changes
+
+Any component can register a listener using:
+
+`SolrCore#addConfListener(Runnable listener)`
+
+to get notified of configuration changes.
+This is not very useful if the files modified result in core reloads (i.e., `configoverlay.xml` or the schema).
+Components can use this to reload the files they are interested in.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/config-sets.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/config-sets.adoc
new file mode 100644
index 0000000..782aeab
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/config-sets.adoc
@@ -0,0 +1,102 @@
+= Configsets
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Configsets are a set of configuration files used in a Solr installation: `solrconfig.xml`, the schema, and xref:resource-loading.adoc[resources] like language files, `synonyms.txt`, and others.
+
+Such configuration, _configsets_, can be named and then referenced by collections or cores, allowing you to share them to avoid duplication.
+
+Solr ships with two example configsets located in `server/solr/configsets`, which can be used as a base for your own.
+These example configsets are named `_default` and `sample_techproducts_configs`.
+
+== Configsets in User-Managed Clusters or Single-Node Installations
+
+If you are using Solr in a user-managed cluster or a single-node installation, configsets are managed on the filesystem.
+
+Each Solr core can have it's very own configset located beneath it in a `<instance_dir>/conf/` dir.
+Here, it is not named or shared and the word _configset_ isn't found.
+In Solr's early years, this was _the only way_ it was configured.
+
+To create a named configset, add a new directory under the configset base directory.
+The configset will be identified by the name of this directory.
+Then add a `conf/` directory containing the configuration you want to share.
+The structure should look something like this:
+
+[source,bash]
+----
+/<configSetBaseDir>
+ /configset1
+ /conf
+ /managed-schema.xml
+ /solrconfig.xml
+ /configset2
+ /conf
+ /managed-schema.xml
+ /solrconfig.xml
+----
+
+The default base directory is `$SOLR_HOME/configsets`.
+This path can be configured with the `configSetBaseDir` parameter in `solr.xml` (see xref:configuring-solr-xml.adoc[] for details).
+
+To create a new core using a configset, pass `configSet` as one of the core properties.
+For example, if you do this via the CoreAdmin API:
+
+[.dynamic-tabs]
+--
+
+[example.tab-pane#v1use-configset]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+curl http://localhost:8983/admin/cores?action=CREATE&name=mycore&instanceDir=path/to/instance&configSet=configset2
+----
+====
+
+[example.tab-pane#v2use-configset]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -v -X POST -H 'Content-type: application/json' -d '{
+ "create":[{
+ "name": "mycore",
+ "instanceDir": "path/to/instance",
+ "configSet": "configSet2"}]}'
+ http://localhost:8983/api/cores
+----
+====
+--
+
+== Configsets in SolrCloud Clusters
+
+In SolrCloud, it's critical to understand that configsets are stored in ZooKeeper _and not_ the file system.
+Solr's `_default` configset is uploaded to ZooKeeper on initialization.
+This and a couple of example configsets remain on the file system but Solr does not use them unless they are used with a new collection.
+
+When you create a collection in SolrCloud, you can specify a named configset.
+If you don't, then the `_default` will be copied and given a unique name for use by the new collection.
+
+A configset can be uploaded to ZooKeeper either via the xref:configsets-api.adoc[] or more directly via xref:deployment-guide:solr-control-script-reference.adoc#upload-a-configuration-set[`bin/solr zk upconfig`].
+The Configsets API has some other operations as well, and likewise, so does the CLI.
+
+To upload a file to a configset already stored on ZooKeeper, you can use xref:deployment-guide:solr-control-script-reference.adoc#copy-between-local-files-and-zookeeper-znodes[`bin/solr zk cp`].
+
+CAUTION: By default, ZooKeeper's file size limit is 1MB.
+If your files are larger than this, you'll need to either xref:deployment-guide:zookeeper-ensemble.adoc#increasing-the-file-size-limit[increase the ZooKeeper file size limit] or store them xref:libs.adoc#lib-directives-in-solrconfig[on the filesystem] of every node in a cluster.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configsets-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configsets-api.adoc
new file mode 100644
index 0000000..6b8d78b
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configsets-api.adoc
@@ -0,0 +1,386 @@
+= Configsets API
+:toclevels: 1
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Configsets API enables you to upload new configsets to ZooKeeper, create, and delete configsets when Solr is running SolrCloud mode.
+
+Configsets are a collection of configuration files such as `solrconfig.xml`, `synonyms.txt`, the schema, language-specific files, and other collection-level configuration files (everything that normally lives in the `conf` directory).
+Solr ships with two example configsets (`_default` and `sample_techproducts_configs`) which can be used when creating collections.
+Using the same concept, you can create your own configsets and make them available when creating collections.
+
+This API provides a way to upload configuration files to ZooKeeper and share the same set of configuration files between two or more collections.
+
+Once a configset has been uploaded to ZooKeeper, use the configset name when creating the collection with the xref:collections-api.adoc[] and the collection will use your configuration files.
+
+Configsets do not have to be shared between collections if they are uploaded with this API, but this API makes it easier to do so if you wish.
+An alternative to uploading your configsets in advance would be to put the configuration files into a directory under `server/solr/configsets` and using the directory name as the `-d` parameter when using `bin/solr create` to create a collection.
+
+NOTE: This API can only be used with Solr running in SolrCloud mode.
+If you are not running Solr in SolrCloud mode but would still like to use shared configurations, please see the section xref:config-sets.adoc[].
+
+The API works by passing commands to the `configs` endpoint.
+The path to the endpoint varies depending on the API being used: the v1 API uses `solr/admin/configs`, while the v2 API uses `api/cluster/configs`.
+Examples of both types are provided below.
+
+[[configsets-list]]
+== List Configsets
+
+The `list` command fetches the names of the configsets that are available for use during collection creation.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1listconfigset]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `list` command must be capitalized as `LIST`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/configs?action=LIST&omitHeader=true
+
+----
+====
+
+[example.tab-pane#v2listconfigset]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `list` command is implied when there is no data sent with the request.
+
+[source,bash]
+----
+http://localhost:8983/api/cluster/configs?omitHeader=true
+----
+====
+--
+
+The output will look like:
+
+[source,json]
+----
+{
+ "configSets": [
+ "_default",
+ "techproducts",
+ "gettingstarted"
+ ]
+}
+----
+
+[[configsets-upload]]
+== Upload a Configset
+
+Upload a configset, which is sent as a zipped file.
+A single, non-zipped file can also be uploaded with the `filePath` parameter.
+
+This functionality is enabled by default, but can be disabled via a runtime parameter `-Dconfigset.upload.enabled=false`.
+Disabling this feature is advisable if you want to expose Solr installation to untrusted users (even though you should never do that!).
+
+A configset is uploaded in a "trusted" mode if authentication is enabled and the upload operation is performed as an authenticated request.
+Without authentication, a configset is uploaded in an "untrusted" mode.
+Upon creation of a collection using an "untrusted" configset, the following functionality will not work:
+
+* The XSLT transformer (`tr` parameter) cannot be used at request processing time.
+* If specified in the configset, the ScriptUpdateProcessorFactory will not initialize.
+* Collections won't initialize if <lib> directives are used in the configset.
+(Note: Libraries added to Solr's classpath don't need the <lib> directive)
+
+If you use any of these parameters or features, you must have enabled security features in your Solr installation and you must upload the configset as an authenticated user.
+
+The `upload` command takes the following parameters:
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The configset to be created when the upload is complete.
+
+`overwrite`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: see description
+|===
++
+If set to `true`, Solr will overwrite an existing configset with the same name (if false, the request will fail).
+If `filePath` is provided, then this option specifies whether the specified file within the configset should be overwritten if it already exists.
+Default is `false` when using the v1 API, but `true` when using the v2 API.
+
+`cleanup`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
+When overwriting an existing configset (`overwrite=true`), this parameter tells Solr to delete the files in ZooKeeper that existed in the old configset but not in the one being uploaded.
+This parameter cannot be set to true when `filePath` is used.
+
+`filePath`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+This parameter allows the uploading of a single, non-zipped file to the given path under the configset in ZooKeeper.
+This functionality respects the `overwrite` parameter, so a request will fail if the given file path already exists in the configset and overwrite is set to `false`.
+The `cleanup` parameter cannot be set to true when `filePath` is used.
+
+If uploading an entire configset, the body of the request should be a zip file that contains the configset.
+The zip file must be created from within the `conf` directory (i.e., `solrconfig.xml` must be the top level entry in the zip file).
+
+Here is an example on how to create the zip file named "myconfig.zip" and upload it as a configset named "myConfigSet":
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1uploadconfigset]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `upload` command must be capitalized as `UPLOAD`:
+
+[source,bash]
+----
+$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
+
+$ curl -X POST --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"
+----
+
+The same can be achieved using a Unix pipe with a single request as follows:
+
+[source,bash]
+----
+$ (cd server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) | curl -X POST --header "Content-Type:application/octet-stream" --data-binary @- "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"
+----
+====
+
+[example.tab-pane#v2uploadconfigset]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the name of the configset to upload is provided as a path parameter:
+
+[source,bash]
+----
+$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip
+
+$ curl -X PUT --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip
+ "http://localhost:8983/api/cluster/configs/myConfigSet"
+----
+
+With this API, the default behavior is to overwrite the configset if it already exists.
+This behavior can be disabled with the parameter `overwrite=false`, in which case the request will fail if the configset already exists.
+====
+--
+
+Here is an example on how to upload a single file to a configset named "myConfigSet":
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1uploadsinglefile]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `upload` command must be capitalized as `UPLOAD`.
+The filename to upload is provided via the `filePath` parameter:
+
+[source,bash]
+----
+curl -X POST --header "Content-Type:application/octet-stream"
+ --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml
+ "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet&filePath=solrconfig.xml&overwrite=true"
+----
+====
+
+[example.tab-pane#v2uploadsinglefile]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the name of the configset and file are both provided in the URL.
+They can be substituted in `/cluster/configs/__config_name__/__file_name__`.
+The filename may be nested and include `/` characters.
+
+[source,bash]
+----
+curl -X PUT --header "Content-Type:application/octet-stream"
+ --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml
+ "http://localhost:8983/api/cluster/configs/myConfigSet/solrconfig.xml"
+----
+
+With this API, the default behavior is to overwrite the file if it already exists within the configset.
+This behavior can be disabled with the parameter `overwrite=false`, in which case the request will fail if the file already exists within the configset.
+====
+--
+
+[[configsets-create]]
+== Create a Configset
+
+The `create` command creates a new configset based on a configset that has been previously uploaded.
+
+If you have not yet uploaded any configsets, see the <<Upload a Configset>> command above.
+
+The following parameters are supported when creating a configset.
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The configset to be created.
+
+`baseConfigSet`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `_default`
+|===
++
+The name of the configset to copy as a base.
+
+`configSetProp._property_=_value_`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A configset property from the base configset to override in the copied configset.
+
+For example, to create a configset named "myConfigset" based on a previously defined "predefinedTemplate" configset, overriding the immutable property to false.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1createconfigset]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `create` command must be capitalized as `CREATE`:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/configs?action=CREATE&name=myConfigSet&baseConfigSet=predefinedTemplate&configSetProp.immutable=false&wt=xml&omitHeader=true
+----
+====
+
+[example.tab-pane#v2createconfigset]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `create` command is provided as part of the JSON data that contains the required parameters:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{
+ "create":{
+ "name": "myConfigSet",
+ "baseConfigSet": "predefinedTemplate",
+ "configSetProp.immutable": "false"}}'
+ http://localhost:8983/api/cluster/configs?omitHeader=true
+----
+
+With the v2 API, configset properties can also be provided via the `properties` map:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{
+ "create":{
+ "name": "myConfigSet",
+ "baseConfigSet": "predefinedTemplate",
+ "properties": {
+ "immutable": "false"
+ }}}'
+ http://localhost:8983/api/cluster/configs?omitHeader=true
+----
+====
+--
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">323</int>
+ </lst>
+</response>
+----
+
+[[configsets-delete]]
+== Delete a Configset
+
+The `delete` command removes a configset.
+It does not remove any collections that were created with the configset.
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The configset to be deleted.
+
+To delete a configset named "myConfigSet":
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1deleteconfigset]
+====
+[.tab-label]*V1 API*
+
+With the v1 API, the `delete` command must be capitalized as `DELETE`.
+The name of the configset to delete is provided with the `name` parameter:
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/configs?action=DELETE&name=myConfigSet&omitHeader=true
+----
+====
+
+[example.tab-pane#v2deleteconfigset]
+====
+[.tab-label]*V2 API*
+
+With the v2 API, the `delete` command is provided as the request method, as in `-X DELETE`.
+The name of the configset to delete is provided as a path parameter:
+
+[source,bash]
+----
+curl -X DELETE http://localhost:8983/api/cluster/configs/myConfigSet?omitHeader=true
+----
+====
+--
+
+*Output*
+
+[source,xml]
+----
+<response>
+ <lst name="responseHeader">
+ <int name="status">0</int>
+ <int name="QTime">170</int>
+ </lst>
+</response>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
new file mode 100644
index 0000000..9cb7be6
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc
@@ -0,0 +1,107 @@
+= Solr Configuration Files
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Solr has several configuration files that you will interact with during your implementation.
+
+Many of these files are in XML format, although APIs that interact with configuration settings tend to accept JSON for programmatic access as needed.
+
+== Solr Home
+When Solr runs, it needs access to a home directory.
+
+When you first install Solr, your home directory is `server/solr`.
+However, some examples may change this location (such as, if you run `bin/solr start -e cloud`, your home directory will be `example/cloud`).
+
+The home directory contains important configuration information and is the place where Solr will store its index.
+The layout of the home directory will look a little different when you are running Solr in a user-managed cluster or single-node installation vs. when you are running a SolrCloud cluster.
+
+The crucial parts of the Solr home directory are shown in these examples:
+
+.User-Managed Cluster or Single-Node
+[source,plain]
+----
+<solr-home-directory>/
+ solr.xml
+ core_name1/
+ core.properties
+ conf/
+ solrconfig.xml
+ managed-schema.xml
+ data/
+ core_name2/
+ core.properties
+ conf/
+ solrconfig.xml
+ managed-schema.xml
+ data/
+----
+
+.SolrCloud
+[source,plain]
+----
+<solr-home-directory>/
+ solr.xml
+ core_name1/
+ core.properties
+ data/
+ core_name2/
+ core.properties
+ data/
+----
+
+You may see other files, but the main ones you need to know are discussed below.
+
+== Solr's Configuration Files
+Inside Solr's Home, you'll find these files:
+
+* `solr.xml` specifies configuration options for your Solr server instance.
+For more information on `solr.xml` see xref:configuring-solr-xml.adoc[].
+* Per Solr Core:
+** `core.properties` defines specific properties for each core such as its name, the collection the core belongs to, the location of the schema, and other parameters.
+For more details on `core.properties`, see the section xref:core-discovery.adoc[].
+** `solrconfig.xml` controls high-level behavior.
+You can, for example, specify an alternate location for the data directory.
+For more information on `solrconfig.xml`, see xref:configuring-solrconfig-xml.adoc[].
+** `managed-schema.xml` or `schema.xml` describes the documents you will ask Solr to index.
+The schema defines a document as a collection of fields.
+You can define both the field types and the fields themselves.
+Field type definitions are powerful and include information about how Solr processes incoming field values and query values.
+For more information on Solr schemas, see xref:indexing-guide:schema-elements.adoc[].
+** `data/` contains index files.
+
+Note that the SolrCloud example does not include a `conf` directory for each Solr Core (so there is no `solrconfig.xml` or schema file).
+This is because the configuration files usually found in the `conf` directory are stored in ZooKeeper so they can be propagated across the cluster.
+
+If you are using SolrCloud with the embedded ZooKeeper instance, you may also see `zoo.cfg` and `zoo.data` which are ZooKeeper configuration and data files.
+However, if you are running your own ZooKeeper ensemble, you would supply your own ZooKeeper configuration file when you start it and the copies in Solr would be unused.
+
+== Files Screen
+
+The Files screen in the Admin UI lets you browse & view configuration files (such `solrconfig.xml` and the schema file) for the collection you selected.
+
+.The Files Screen
+image::configuration-files/files-screen.png[Files screen,height=400]
+
+If you are using xref:deployment-guide:cluster-types.adoc#solrcloud-mode[SolrCloud], the files displayed are the configuration files for this collection stored in ZooKeeper.
+In user-managed clusters or single-node installations, all files in the `conf` directory are displayed.
+
+The configuration files shown may or may not be used by the collection as use of the file depends on how they are referenced in either `solrconfig.xml` or your schema.
+
+Configuration files cannot be edited with this screen, so a text editor of some kind must be used.
+
+This screen is related to the xref:indexing-guide:schema-browser-screen.adoc[], in that they both can display information from the schema.
+However, the Schema Browser provides a way to drill into the analysis chain and displays linkages between field types, fields, and dynamic field rules.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solr-xml.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solr-xml.adoc
new file mode 100644
index 0000000..9f19550
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solr-xml.adoc
@@ -0,0 +1,593 @@
+= Configuring solr.xml
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The `solr.xml` file defines some global configuration options that apply to all or many cores.
+
+This section will describe the default `solr.xml` file included with Solr and how to modify it for your needs.
+For details on how to configure `core.properties`, see the section xref:core-discovery.adoc[].
+
+== Defining solr.xml
+
+You can find `solr.xml` in your `$SOLR_HOME` directory (usually `server/solr` or `/var/solr/data`) or optionally in ZooKeeper when using SolrCloud. If `$SOLR_HOME/solr.xml` is not found, Solr will use the default `solr.xml` file.
+
+The default `solr.xml` file is found in `$SOLR_TIP/server/solr/solr.xml` and looks like this:
+
+[source,xml]
+----
+<solr>
+
+ <int name="maxBooleanClauses">${solr.max.booleanClauses:1024}</int>
+ <str name="sharedLib">${solr.sharedLib:}</str>
+ <str name="modules">${solr.modules:}</str>
+ <str name="allowPaths">${solr.allowPaths:}</str>
+ <str name="allowUrls">${solr.allowUrls:}</str>
+
+ <solrcloud>
+
+ <str name="host">${host:}</str>
+ <int name="hostPort">${solr.port.advertise:0}</int>
+ <str name="hostContext">${hostContext:solr}</str>
+
+ <bool name="genericCoreNodeNames">${genericCoreNodeNames:true}</bool>
+
+ <int name="zkClientTimeout">${zkClientTimeout:30000}</int>
+ <int name="distribUpdateSoTimeout">${distribUpdateSoTimeout:600000}</int>
+ <int name="distribUpdateConnTimeout">${distribUpdateConnTimeout:60000}</int>
+ <str name="zkCredentialsProvider">${zkCredentialsProvider:org.apache.solr.common.cloud.DefaultZkCredentialsProvider}</str>
+ <str name="zkACLProvider">${zkACLProvider:org.apache.solr.common.cloud.DefaultZkACLProvider}</str>
+ <bool name="distributedClusterStateUpdates">${distributedClusterStateUpdates:false}</bool>
+ <bool name="distributedCollectionConfigSetExecution">${distributedCollectionConfigSetExecution:false}</bool>
+
+ </solrcloud>
+
+ <shardHandlerFactory name="shardHandlerFactory"
+ class="HttpShardHandlerFactory">
+ <int name="socketTimeout">${socketTimeout:600000}</int>
+ <int name="connTimeout">${connTimeout:60000}</int>
+ </shardHandlerFactory>
+
+ <metrics enabled="${metricsEnabled:true}">
+ <!--reporter name="jmx_metrics" group="core" class="org.apache.solr.metrics.reporters.SolrJmxReporter"/-->
+ </metrics>
+
+</solr>
+----
+
+As you can see, the discovery Solr configuration is "SolrCloud friendly".
+However, the presence of the `<solrcloud>` element does _not_ mean that the Solr instance is running in SolrCloud mode.
+Unless the `-DzkHost` or `-DzkRun` are specified at startup time, this section is ignored.
+
+== Solr.xml Parameters
+
+=== The <solr> Element
+
+There are no attributes that you can specify in the `<solr>` tag, which is the root element of `solr.xml`.
+The tables below list the child nodes of each XML element in `solr.xml`.
+
+`configSetService`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `configSetService`
+|===
++
+This attribute does not need to be set.
++
+If used, this attribute should be set to the FQN (Fully qualified name) of a class that inherits from `ConfigSetService`, and you must provide a constructor with one parameter which the type is `org.apache.solr.core.CoreContainer`.
+For example, `<str name="configSetService">com.myorg.CustomConfigSetService</str>`.
++
+If this attribute isn't set, Solr uses the default `configSetService`, with zookeeper aware of `org.apache.solr.cloud.ZkConfigSetService`, without zookeeper aware of `org.apache.solr.core.FileSystemConfigSetService`.
+
+`adminHandler`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `org.apache.solr.handler.admin.CoreAdminHandler`
+|===
++
+This attribute does not need to be set.
++
+If used, this attribute should be set to the FQN (Fully qualified name) of a class that inherits from CoreAdminHandler.
+For example, `<str name="adminHandler">com.myorg.MyAdminHandler</str>` would configure the custom admin handler (MyAdminHandler) to handle admin requests.
++
+If this attribute isn't set, Solr uses the default admin handler, `org.apache.solr.handler.admin.CoreAdminHandler`.
+
+`collectionsHandler`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+As above, for custom CollectionsHandler implementations.
+
+`infoHandler`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+As above, for custom InfoHandler implementations.
+
+`coreLoadThreads`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Specifies the number of threads that will be assigned to load cores in parallel.
+
+`replayUpdatesThreads`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Specifies the number of threads that will be assigned to replay updates in parallel.
+This pool is shared for all cores of the node.
+The default value is equal to the number of processors.
+
+`coreRootDirectory`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `server/solr`
+|===
++
+The root of the core discovery tree, defaults to `$SOLR_HOME`.
+
+`managementPath`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Currently non-operational.
+
+`sharedLib`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Specifies the path to a common library directory that will be shared across all cores.
+Any JAR files in this directory will be added to the search path for Solr plugins.
+If the specified path is not absolute, it will be relative to `$SOLR_HOME`.
+Custom handlers may be placed in this directory.
+Note that specifying `sharedLib` will not remove `$SOLR_HOME/lib` from Solr's class path.
+
+`modules`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Takes a list of bundled xref:solr-modules.adoc[solr modules] to add to Solr's class path
+on startup. This way of adding modules will add them to the shared class loader, making them
+available for every collection in Solr, unlike `<lib>` tag in `solrconfig.xml` which is only
+for that one collection. Example value: `extracting,ltr`. See the
+xref:solr-modules.adoc[Solr Modules] chapter for more details.
+
+`allowPaths`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Solr will normally only access folders relative to `$SOLR_HOME`, `$SOLR_DATA_HOME` or `coreRootDir`.
+If you need to e.g., create a core outside of these paths, you can explicitly allow the path with `allowPaths`.
+It is a comma separated string of file system paths to allow.
+The special value of `*` will allow any path on the system.
+
+[#allow-urls]
+`allowUrls`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Comma-separated list of Solr hosts to allow.
++
+The HTTP/HTTPS protocol may be omitted, and only the host and port are checked, i.e., `10.0.0.1:8983/solr,10.0.0.1:8984/solr`.
++
+When running Solr as a user-managed cluster and using the `shards` parameter, a list of hosts needs to be specifically configured as allowed or Solr will forbid the request.
++
+In SolrCloud mode, the allow-list is automatically configured to include all live nodes in the cluster.
++
+The allow-list can also be configured with the `solr.allowUrls` system property in `solr.in.sh` / `solr.in.cmd`.
+If you need to disable this feature for backwards compatibility, you can set the system property `solr.disable.allowUrls=true`.
+
+`shareSchema`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+This attribute, when set to `true`, ensures that the multiple cores pointing to the same Schema resource file will be referring to the same IndexSchema Object.
+Sharing the IndexSchema Object makes loading the core faster.
+If you use this feature, make sure that no core-specific property is used in your Schema file.
+
+`transientCacheSize`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Defines how many cores with `transient=true` that can be loaded before swapping the least recently used core for a new core.
+
+`configSetBaseDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `$SOLR_HOME/configsets`
+|===
++
+The directory under which configsets for Solr cores can be found.
+
+[[global-maxbooleanclauses]]
+`maxBooleanClauses`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Sets the maximum number of (nested) clauses allowed in any query.
++
+This global limit provides a safety constraint on the total number of clauses allowed in any query against any collection -- regardless of whether those clauses were explicitly specified in a query string, or were the result of query expansion/re-writing from a more complex type of query based on the terms in the index.
+This limit is enforced at multiple points in Lucene, both to prevent primitive query objects (mainly `BooleanQuery`) from being constructed with an excessive number of clauses in a way that may exhaust the JVM heap, but also to ensure that no composite query (made up of multiple primitive queries) can be executed with an excessive _total_ number of nested clauses in a way that may cause a search thread to use excessive CPU.
++
+In default configurations this property uses the value of the `solr.max.booleanClauses` system property if specified.
+This is the same system property used in the `_default` configset for the xref:caches-warming.adoc#maxbooleanclauses-element[`<maxBooleanClauses>` element of `solrconfig.xml`] making it easy for Solr administrators to increase both values (in all collections) without needing to search through and update all of their configs.
++
+[source,xml]
+----
+<maxBooleanClauses>${solr.max.booleanClauses:1024}</maxBooleanClauses>
+----
+
+=== The <solrcloud> Element
+
+This element defines several parameters that relate so SolrCloud.
+This section is ignored unless theSolr instance is started with either `-DzkRun` or `-DzkHost`
+
+`distribUpdateConnTimeout`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Used to set the underlying `connTimeout` for intra-cluster updates.
+
+`distribUpdateSoTimeout`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Used to set the underlying `socketTimeout` for intra-cluster updates.
+
+`host`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The hostname Solr uses to access cores.
+
+`hostContext`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The url context path.
+
+`hostPort`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `${solr.port.advertise:0}`
+|===
++
+The port Solr uses to access cores, and advertise Solr node locations through liveNodes.
+This option is only necessary if a Solr instance is listening on a different port than it wants other nodes to contact it at.
+For example, if the Solr node is running behind a proxy or in a cloud environment that allows for port mapping, such as Kubernetes.
+`hostPort` is the port that the Solr instance wants other nodes to contact it at.
++
+In the default `solr.xml` file, this is set to `${solr.port.advertise:0}`.
+If no port is passed via the `solr.xml` (i.e., `0`), then Solr will default to the port that jetty is listening on, defined by `${jetty.port}`.
+
+`leaderVoteWait`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+When SolrCloud is starting up, how long each Solr node will wait for all known replicas for that shard to be found before assuming that any nodes that haven't reported are down.
+
+`leaderConflictResolveWait`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `180000` milliseconds
+|===
++
+When trying to elect a leader for a shard, this property sets the maximum time a replica will wait to see conflicting state information to be resolved; temporary conflicts in state information can occur when doing rolling restarts, especially when the node hosting the Overseer is restarted.
++
+Typically, the default value of `180000` (ms) is sufficient for conflicts to be resolved; you may need to increase this value if you have hundreds or thousands of small collections in SolrCloud.
+
+`zkClientTimeout`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A timeout for connection to a ZooKeeper server.
+It is used with SolrCloud.
+
+`zkHost`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+In SolrCloud mode, the URL of the ZooKeeper host that Solr should use for cluster state information.
+
+`genericCoreNodeNames`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+If `true`, node names are not based on the address of the node, but on a generic name that identifies the core.
+When a different machine takes over serving that core things will be much easier to understand.
+
+`zkCredentialsProvider` & `zkACLProvider`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Optional parameters that can be specified if you are using xref:deployment-guide:zookeeper-access-control.adoc[].
+
+`distributedClusterStateUpdates`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+If `true`, the internal behavior of SolrCloud is changed to not use the Overseer for collections' `state.json` updates but do this directly against ZooKeeper.
+
+=== The <logging> Element
+
+`class`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The class to use for logging.
+The corresponding JAR file must be available to Solr, perhaps through a `<lib>` directive in `solrconfig.xml`.
+
+`enabled`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+Whether to enable logging or not.
+
+==== The <logging><watcher> Element
+
+`size`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `50`
+|===
++
+The number of log events that are buffered.
+
+`threshold`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The logging level above which your particular logging implementation will record.
+For example when using Log4j one might specify DEBUG, WARN, INFO, etc.
+
+=== The <shardHandlerFactory> Element
+
+Custom shard handlers can be defined in `solr.xml` if you wish to create a custom shard handler.
+
+[source,xml]
+----
+<shardHandlerFactory name="ShardHandlerFactory" class="qualified.class.name">
+----
+
+Since this is a custom shard handler, sub-elements are specific to the implementation.
+The default and only shard handler provided by Solr is the `HttpShardHandlerFactory` in which case, the following sub-elements can be specified:
+
+`socketTimeout`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The read timeout for intra-cluster query and administrative requests.
+The default is the same as the `distribUpdateSoTimeout` specified in the `<solrcloud>` section.
+
+`connTimeout`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The connection timeout for intra-cluster query and administrative requests.
+Defaults to the `distribUpdateConnTimeout` specified in the `<solrcloud>` section.
+
+`urlScheme`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The URL scheme to be used in distributed search.
+
+`maxConnectionsPerHost`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `100000`
+|===
++
+Maximum connections allowed per host.
+
+`corePoolSize`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `0`
+|===
++
+The initial core size of the threadpool servicing requests.
+
+`maximumPoolSize`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum size of the threadpool servicing requests.
+Default is unlimited.
+
+`maxThreadIdleTime`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `5` seconds
+|===
++
+The amount of time in seconds that idle threads persist for in the queue, before being killed.
+
+`sizeOfQueue`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+If the threadpool uses a backing queue, what is its maximum size to use direct handoff.
+Default is to use a SynchronousQueue.
+
+`fairnessPolicy`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+A boolean to configure if the threadpool favors fairness over throughput.
+
+`replicaRouting`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+A NamedList specifying replica routing preference configuration.
+This may be used to select and configure replica routing preferences.
+`default=true` may be used to set the default base replica routing preference.
+Only positive default status assertions are respected; i.e., `default=false` has no effect.
+If no explicit default base replica routing preference is configured, the implicit default will be `random`.
+----
+<shardHandlerFactory class="HttpShardHandlerFactory">
+ <lst name="replicaRouting">
+ <lst name="stable">
+ <bool name="default">true</bool>
+ <str name="dividend">routingDividend</str>
+ <str name="hash">q</str>
+ </lst>
+ </lst>
+</shardHandlerFactory>
+----
+Replica routing may also be specified (overriding defaults) per-request, via the `shards.preference` request parameter.
+If a request contains both `dividend` and `hash`, `dividend` takes priority for routing.
+For configuring `stable` routing, the `hash` parameter implicitly defaults to a hash of the String value of the main query parameter (i.e., `q`).
++
+The `dividend` parameter must be configured explicitly; there is no implicit default.
+If only `dividend` routing is desired, `hash` may be explicitly set to the empty string, entirely disabling implicit hash-based routing.
+
+=== The <metrics> Element
+
+The `<metrics>` element in `solr.xml` allows you to customize the metrics reported by Solr.
+You can define system properties that should not be returned, or define custom suppliers and reporters.
+
+If you would like to customize the metrics for your installation, see the xref:deployment-guide:metrics-reporting.adoc#metrics-configuration[Metrics Configuration] section.
+
+== Substituting JVM System Properties in solr.xml
+
+Solr supports variable substitution of JVM system property values in `solr.xml`, which allows runtime specification of various configuration options.
+The syntax is `${propertyname[:option default value]}`.
+This allows defining a default that can be overridden when Solr is launched.
+If a default value is not specified, then the property must be specified at runtime or the `solr.xml` file will generate an error when parsed.
+
+Any JVM system properties usually specified using the `-D` flag when starting the JVM, can be used as variables in the `solr.xml` file.
+
+For example, in the `solr.xml` file shown below, the `socketTimeout` and `connTimeout` values are each set to "60000".
+However, if you start Solr using `bin/solr -DsocketTimeout=1000`, the `socketTimeout` option of the `HttpShardHandlerFactory` to be overridden using a value of 1000ms, while the `connTimeout` option will continue to use the default property value of "60000".
+
+[source,xml]
+----
+<solr>
+ <shardHandlerFactory name="shardHandlerFactory"
+ class="HttpShardHandlerFactory">
+ <int name="socketTimeout">${socketTimeout:60000}</int>
+ <int name="connTimeout">${connTimeout:60000}</int>
+ </shardHandlerFactory>
+</solr>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solrconfig-xml.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solrconfig-xml.adoc
new file mode 100644
index 0000000..3680b92
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configuring-solrconfig-xml.adoc
@@ -0,0 +1,75 @@
+= Configuring solrconfig.xml
+:page-children: index-location-format, \
+ index-segments-merging, \
+ schema-factory, \
+ commits-transaction-logs, \
+ caches-warming, \
+ requesthandlers-searchcomponents, \
+ implicit-requesthandlers, \
+ realtime-get, \
+ initparams, \
+ requestdispatcher, \
+ update-request-processors, \
+ script-update-processor, \
+ codec-factory
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The `solrconfig.xml` file is the configuration file with the most parameters affecting Solr itself.
+
+While configuring Solr, you'll work with `solrconfig.xml` often, either directly or via the xref:config-api.adoc[] to create "configuration overlays" (`configoverlay.json`) to override the values in `solrconfig.xml`.
+
+In `solrconfig.xml`, you configure important features such as:
+
+* request handlers, which process the requests to Solr, such as requests to add documents to the index or requests to return results for a query
+
+* listeners, processes that "listen" for particular query-related events; listeners can be used to trigger the execution of special code, such as invoking some common queries to warm-up caches
+
+* the Request Dispatcher for managing HTTP communications
+
+* the Admin Web interface
+
+* parameters related to replication and duplication when not running in SolrCloud mode
+
+The `solrconfig.xml` file is located in the `conf/` directory for each collection.
+Several well-commented example files can be found in the `server/solr/configsets/` directories demonstrating best practices for many different types of installations.
+
+Some `solrconfig.xml` aspects are documented in other sections.
+See xref:libs.adoc#lib-directives-in-solrconfig[lib directives in SolrConfig], which can be used for both Plugins and Resources.
+
+****
+// This tags the below list so it can be used in the parent page section list
+// tag::solrconfig-sections[]
+[cols="1,1",frame=none,grid=none,stripes=none]
+|===
+| xref:index-location-format.adoc[]: Where and how Solr's indexes are stored.
+| xref:index-segments-merging.adoc[]: Lucene index writers, including segment management, merges, and locks.
+| xref:schema-factory.adoc[]: Schema file formats.
+| xref:commits-transaction-logs.adoc[]: Update requests and commit settings.
+| xref:caches-warming.adoc[]: Caches, query warming, and query listeners.
+| xref:requesthandlers-searchcomponents.adoc[]: Request processors and handlers for search features.
+| xref:implicit-requesthandlers.adoc[]: Request end-points automatically provided by Solr.
+| xref:realtime-get.adoc[]: Get the latest version of a document without opening a searcher.
+| xref:initparams.adoc[]: Default parameters for request handlers.
+| xref:requestdispatcher.adoc[]: Advanced request parsing and HTTP cache headers.
+| xref:update-request-processors.adoc[]: Plugins for update requests.
+| xref:script-update-processor.adoc[]: Java scripting engines during document updates.
+| xref:codec-factory.adoc[]: Lucene codecs when writing data to disk.
+|
+|===
+//end::solrconfig-sections[]
+****
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/core-discovery.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/core-discovery.adoc
new file mode 100644
index 0000000..3dab912
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/core-discovery.adoc
@@ -0,0 +1,219 @@
+= Core Discovery
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Core discovery means that creating a core is as simple as a `core.properties` file located on disk.
+
+== The core.properties File
+
+In Solr, the term _core_ is used to refer to a single index and associated transaction log and configuration files (including the `solrconfig.xml` and schema files, among others).
+Your Solr installation can have multiple cores if needed, which allows you to index data with different structures in the same server, and maintain control over how your data is presented to different audiences.
+In SolrCloud mode you will be more familiar with the term _collection_.
+Behind the scenes a collection consists of one or more cores.
+
+Cores can be created using `bin/solr` script or as part of SolrCloud collection creation using the APIs.
+Core-specific properties (such as the directories to use for the indexes or configuration files, the core name, and other options) are defined in a `core.properties` file.
+Any `core.properties` file in any directory of your Solr installation (or in a directory under where `solr_home` is defined) will be found by Solr and the defined properties will be used for the core named in the file.
+
+The `core.properties` file is a simple Java Properties file where each line is just a key=value pair, e.g., `name=core1`.
+Notice that no quotes are required.
+
+==
+A minimal `core.properties` file looks like the example below.
+However, it can also be empty, see information on placement of `core.properties` below.
+
+[source,bash]
+----
+name=my_core_name
+----
+
+== Placement of core.properties
+
+Solr cores are configured by placing a file named `core.properties` in a sub-directory under `solr.home`.
+There are no a-priori limits to the depth of the tree, nor are there limits to the number of cores that can be defined.
+Cores may be anywhere in the tree with the exception that cores may _not_ be defined under an existing core.
+That is, the following is not allowed:
+
+[source,text]
+----
+./cores/core1/core.properties
+./cores/core1/coremore/core5/core.properties
+----
+
+In this example, the enumeration will stop at "core1".
+
+The following is legal:
+
+[source,text]
+----
+./cores/somecores/core1/core.properties
+./cores/somecores/core2/core.properties
+./cores/othercores/core3/core.properties
+./cores/extracores/deepertree/core4/core.properties
+----
+
+It is possible to segment Solr into multiple cores, each with its own configuration and indices.
+Cores may be dedicated to a single application or to very different ones, but all are administered through a common administration interface.
+You can create new Solr cores on the fly, shutdown cores, even replace one running core with another, all without ever stopping or restarting Solr.
+
+Your `core.properties` file can be empty if necessary.
+Suppose `core.properties` is located in `./cores/core1` (relative to `solr_home`) but is empty.
+In this case, the core name is assumed to be "core1".
+The instanceDir will be the folder containing `core.properties` (i.e., `./cores/core1`).
+The dataDir will be `../cores/core1/data`, etc.
+
+[NOTE]
+====
+You can run Solr without configuring any cores.
+====
+
+== Defining core.properties Files
+
+The minimal `core.properties` file is an empty file, in which case all of the properties are defaulted appropriately.
+
+Java properties files allow the hash (`#`) or bang (`!`) characters to specify comment-to-end-of-line.
+
+The following properties are available:
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of the SolrCore.
+You'll use this name to reference the SolrCore when running commands with the `CoreAdminHandler`.
+
+`config`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `solrconfig.xml`
+|===
++
+The configuration file name for a given core.
+
+`schema`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The schema file name for a given core.
+The default is `schema.xml` but please note that if you are using a "managed schema" (the default behavior) then any value for this property which does not match the effective `managedSchemaResourceName` will be read once, backed up, and converted for managed schema use.
+See xref:schema-factory.adoc[] for more details.
+
+`dataDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `data`
+|===
++
+The core's data directory (where indexes are stored) as either an absolute pathname, or a path relative to the value of `instanceDir`.
+
+`configSet`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of a defined configset, if desired, to use to configure the core (see the section xref:config-sets.adoc[] for more details).
+
+`properties`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of the properties file for this core.
+The value can be an absolute pathname or a path relative to the value of `instanceDir`.
+
+`transient`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+When `true`, the core can be unloaded if Solr reaches the `transientCacheSize`.
+Cores are unloaded in order of least recently used first.
+_Setting this to `true` is not recommended in SolrCloud mode._
+
+`loadOnStartup`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+When `true`, the default, the core will loaded when Solr starts.
+_Setting this to `false` is not recommended in SolrCloud mode._
+
+`coreNodeName`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Used only in SolrCloud, this is a unique identifier for the node hosting this replica.
+By default a `coreNodeName` is generated automatically, but setting this attribute explicitly allows you to manually assign a new core to replace an existing replica.
+For example, this can be useful when replacing a machine that has had a hardware failure by restoring from backups on a new machine with a new hostname or port.
+
+`ulogDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The absolute or relative directory for the update log for this core (SolrCloud only).
+
+`shard`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The shard to assign this core to (SolrCloud only).
+
+`collection`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of the collection this core is part of (SolrCloud only).
+
+`roles`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Future parameter for SolrCloud or a way for users to mark nodes for their own use.
+
+Additional user-defined properties may be specified for use as variables.
+For more information on how to define local properties, see the section xref:property-substitution.adoc[].
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/coreadmin-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/coreadmin-api.adoc
new file mode 100644
index 0000000..cd33ea9
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/coreadmin-api.adoc
@@ -0,0 +1,728 @@
+= CoreAdmin API
+:toclevels: 1
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Core Admin API is primarily used under the covers by the xref:collections-api.adoc[] when running a xref:deployment-guide:cluster-types.adoc#solrcloud-mode[SolrCloud] cluster.
+
+SolrCloud users should not typically use the CoreAdmin API directly, but the API may be useful for users of user-managed clusters or single-node installations for core maintenance operations.
+
+The CoreAdmin API is implemented by the CoreAdminHandler, which is a special purpose xref:requesthandlers-searchcomponents.adoc[request handler] that is used to manage Solr cores.
+Unlike other request handlers, the CoreAdminHandler is not attached to a single core.
+Instead, there is a single instance of the CoreAdminHandler in each Solr node that manages all the cores running in that node and is accessible at the `/solr/admin/cores` path.
+
+CoreAdmin actions can be executed by via HTTP requests that specify an `action` request parameter, with additional action specific arguments provided as additional parameters.
+
+All action names are uppercase, and are defined in depth in the sections below.
+
+All of the examples in this section assume you are running the "techproducts" Solr example:
+
+[source,bash]
+----
+bin/solr start -DconfigSetBaseDir=./server/solr/configsets -e techproducts
+----
+
+We are passing in the explicit relative path for the `configSetBaseDir` to enable creating new cores using the `sample_techproducts_configs` configset in the examples below.
+
+[[coreadmin-status]]
+== STATUS
+
+The `STATUS` action returns the status of all running Solr cores, or status for only the named core.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1coreadmin-status]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/cores?action=STATUS&core=techproducts
+
+----
+====
+
+[example.tab-pane#v2coreadmin-status]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X GET http://localhost:8983/api/cores/
+----
+
+To get the status for a single core:
+
+[source,bash]
+----
+curl -X GET http://localhost:8983/api/cores/techproducts
+----
+
+To skip returning information about the index:
+
+[source,bash]
+----
+curl -X GET http://localhost:8983/api/cores?indexInfo=false
+----
+
+====
+--
+
+=== STATUS Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of a core, as listed in the "name" attribute of a `<core>` element in `solr.xml`.
+This parameter is required in v1, and part of the url in the v2 API.
+
+`indexInfo`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+If `false`, information about the index will not be returned with a core STATUS request.
+In Solr implementations with a large number of cores (i.e., more than hundreds), retrieving the index information for each core can take a lot of time and isn't always required.
+
+[[coreadmin-create]]
+== CREATE
+
+The `CREATE` action creates a new core and registers it.
+
+If a Solr core with the given name already exists, it will continue to handle requests while the new core is initializing.
+When the new core is ready, it will take new requests and the old core will be unloaded.
+
+`admin/cores?action=CREATE&name=_core-name_&instanceDir=_path/to/dir_&config=solrconfig.xml&dataDir=data`
+[.dynamic-tabs]
+--
+[example.tab-pane#v1coreadmin-create]
+====
+[.tab-label]*V1 API*
+
+Assuming you are using an existing configSet to create your new core:
+[source,bash]
+----
+http://localhost:8983/solr/admin/cores?action=CREATE&&name=techproducts_v2&configSet=sample_techproducts_configs
+
+----
+
+If you have already existing core files deployed on disk, and need to just create the Solr core from them then the url will look something like
+[source,bash]
+----
+http://localhost:8983/solr/admin/cores?action=CREATE&name=_core-name_&instanceDir=_path/to/dir_&config=solrconfig.xml&dataDir=data
+----
+====
+
+[example.tab-pane#v2coreadmin-create]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/api/cores -H 'Content-Type: application/json' -d '
+ {
+ "create": {
+ "name": "techproducts_v2",
+ "configSet": "sample_techproducts_configs"
+ }
+ }
+'
+----
+====
+--
+
+Note that this command is the only one of the Core Admin API commands that *does not* support the `core` parameter.
+Instead, the `name` parameter is required, as shown below.
+
+Note that CREATE must be able to find a configuration or it will not succeed.
+
+When you are running SolrCloud and create a new core for a collection, the configuration will be inherited from the collection.
+Each collection is linked to a `configName`, which is stored in ZooKeeper.
+This satisfies the configuration requirement.
+That said, if you're running SolrCloud, you should *NOT* use the CoreAdmin API at all.
+Instead, use the xref:collections-api.adoc[].
+
+With a user-managed cluster, if you have xref:config-sets.adoc[] defined, you can use the `configSet` parameter as documented below.
+If there are no configsets, then the `instanceDir` specified in the CREATE call must already exist, and it must contain a `conf` directory which in turn must contain `solrconfig.xml`, your schema (usually named either `managed-schema.xml` or `schema.xml`), and any files referenced by those configs.
+
+The config and schema filenames can be specified with the `config` and `schema` parameters, but these are expert options.
+One thing you could do to avoid creating the `conf` directory is use `config` and `schema` parameters that point at absolute paths, but this can lead to confusing configurations unless you fully understand what you are doing.
+
+.CREATE and the `core.properties` file
+[IMPORTANT]
+====
+The `core.properties` file is built as part of the CREATE command.
+If you create a `core.properties` file yourself in a core directory and then try to use CREATE to add that core to Solr, you will get an error telling you that another core is already defined there.
+The `core.properties` file must NOT exist before calling the CoreAdmin API with the CREATE command.
+====
+
+=== CREATE Core Parameters
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the new core.
+Same as `name` on the `<core>` element.
+
+`instanceDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The directory where files for this core should be stored.
+Same as `instanceDir` on the `<core>` element.
+The default is the value specified for the `name` parameter if not supplied.
+This directory must be inside `SOLR_HOME`, `SOLR_DATA_HOME` or one of the paths specified by system property `solr.allowPaths`.
+
+`config`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `solrconfig.xml`
+|===
++
+Name of the config file (i.e., `solrconfig.xml`) relative to `instanceDir`.
+
+`schema`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Name of the schema file to use for the core.
+Please note that if you are using a "managed schema" (the default behavior) then any value for this property which does not match the effective `managedSchemaResourceName` will be read once, backed up, and converted for managed schema use.
+See xref:schema-factory.adoc[] for details.
+
+`dataDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `data`
+|===
++
+Name of the data directory relative to `instanceDir`.
+If absolute value is used, it must be inside `SOLR_HOME`, `SOLR_DATA_HOME` or one of the paths specified by system property `solr.allowPaths`.
+
+`configSet`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Name of the configset to use for this core.
+For more information, see the section xref:config-sets.adoc[].
+
+`collection`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The name of the collection to which this core belongs.
+The default is the name of the core.
+`collection._param_=_value_` causes a property of `_param_=_value_` to be set if a new collection is being created.
+Use `collection.configName=_config-name_` to point to the configuration for a new collection.
++
+WARNING: While it's possible to create a core for a non-existent collection, this approach is not supported and not recommended.
+Always create a collection using the xref:collections-api.adoc[] before creating a core directly for it.
+
+`shard`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The shard ID this core represents.
+This should only be required in special circumstances; normally you want to be auto-assigned a shard ID.
+
+`property._name_=_value_`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Sets the core property _name_ to _value_.
+See the section on defining xref:core-discovery.adoc#defining-core-properties-files[core.properties file contents].
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+Use `collection.configName=_configname_` to point to the config for a new collection.
+
+=== CREATE Example
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=CREATE&name=my_core&collection=my_collection&shard=shard2
+
+
+[[coreadmin-reload]]
+== RELOAD
+
+The RELOAD action loads a new core from the configuration of an existing, registered Solr core.
+While the new core is initializing, the existing one will continue to handle requests.
+When the new Solr core is ready, it takes over and the old core is unloaded.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1coreadmin-reload]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/cores?action=RELOAD&core=techproducts
+
+----
+====
+
+[example.tab-pane#v2coreadmin-reload]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST http://localhost:8983/api/cores/techproducts -H 'Content-Type: application/json' -d '
+ {
+ "reload": {}
+ }
+'
+----
+====
+--
+
+This is useful when you've made changes to a Solr core's configuration on disk, such as adding new field definitions.
+Calling the RELOAD action lets you apply the new configuration without having to restart Solr.
+
+[IMPORTANT]
+====
+RELOAD performs "live" reloads of SolrCore, reusing some existing objects.
+Some configuration options, such as the `dataDir` location and `IndexWriter`-related settings in `solrconfig.xml` can not be changed and made active with a simple RELOAD action.
+====
+
+=== RELOAD Core Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of the core, as listed in the "name" attribute of a `<core>` element in `solr.xml`.
+This parameter is required in v1, and part of the url in the v2 API.
+
+[[coreadmin-rename]]
+== RENAME
+
+The `RENAME` action changes the name of a Solr core.
+
+`admin/cores?action=RENAME&core=_core-name_&other=_other-core-name_`
+
+=== RENAME Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the Solr core to be renamed.
+
+`other`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The new name for the Solr core.
+If the persistent attribute of `<solr>` is `true`, the new name will be written to `solr.xml` as the `name` attribute of the `<core>` attribute.
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+
+[[coreadmin-swap]]
+== SWAP
+
+`SWAP` atomically swaps the names used to access two existing Solr cores.
+This can be used to swap new content into production.
+The prior core remains available and can be swapped back, if necessary.
+Each core will be known by the name of the other, after the swap.
+
+`admin/cores?action=SWAP&core=_core-name_&other=_other-core-name_`
+
+[IMPORTANT]
+====
+Do not use `SWAP` with a SolrCloud node.
+It is not supported and can result in the core being unusable.
+====
+
+=== SWAP Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of one of the cores to be swapped.
+
+`other`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the other core to be swapped.
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+
+[[coreadmin-unload]]
+== UNLOAD
+
+The `UNLOAD` action removes a core from Solr.
+Active requests will continue to be processed, but no new requests will be sent to the named core.
+If a core is registered under more than one name, only the given name is removed.
+
+`admin/cores?action=UNLOAD&core=_core-name_`
+
+The `UNLOAD` action requires a parameter (`core`) identifying the core to be removed.
+If the persistent attribute of `<solr>` is set to `true`, the `<core>` element with this `name` attribute will be removed from `solr.xml`.
+
+[IMPORTANT]
+====
+Unloading all cores in a SolrCloud collection causes the removal of that collection's metadata from ZooKeeper.
+====
+
+=== UNLOAD Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of a core to be removed.
+This parameter is required.
+
+`deleteIndex`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+If `true`, will remove the index when unloading the core.
+
+`deleteDataDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+If `true`, removes the `data` directory and all sub-directories.
+
+`deleteInstanceDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+If `true`, removes everything related to the core, including the index directory, configuration files and other related files.
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+[[coreadmin-mergeindexes]]
+== MERGEINDEXES
+
+The `MERGEINDEXES` action merges one or more indexes to another index.
+The indexes must have completed commits, and should be locked against writes until the merge is complete or the resulting merged index may become corrupted.
+The target core index must already exist and have a compatible schema with the one or more indexes that will be merged to it.
+Another commit on the target core should also be performed after the merge is complete.
+
+`admin/cores?action=MERGEINDEXES&core=_new-core-name_&indexDir=_path/to/core1/data/index_&indexDir=_path/to/core2/data/index_`
+
+In this example, we use the `indexDir` parameter to define the index locations of the source cores.
+The `core` parameter defines the target index.
+A benefit of this approach is that we can merge any Lucene-based index that may not be associated with a Solr core.
+
+Alternatively, we can instead use a `srcCore` parameter, as in this example:
+
+`admin/cores?action=mergeindexes&core=_new-core-name_&srcCore=_core1-name_&srcCore=_core2-name_`
+
+This approach allows us to define cores that may not have an index path that is on the same physical server as the target core.
+However, we can only use Solr cores as the source indexes.
+Another benefit of this approach is that we don't have as high a risk for corruption if writes occur in parallel with the source index.
+
+We can make this call run asynchronously by specifying the `async` parameter and passing a request ID.
+This ID can then be used to check the status of the already submitted task using the REQUESTSTATUS API.
+
+=== MERGEINDEXES Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the target core/index.
+
+`indexDir`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Multi-valued, directories that would be merged.
+
+`srcCore`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Multi-valued, source cores that would be merged.
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+
+[[coreadmin-split]]
+== SPLIT
+
+The `SPLIT` action splits an index into two or more indexes.
+The index being split can continue to handle requests.
+The split pieces can be placed into a specified directory on the server's filesystem or it can be merged into running Solr cores.
+
+The `SPLIT` action supports five parameters, which are described in the table below.
+
+=== SPLIT Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the core to be split.
+
+`path`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Multi-valued, the directory path in which a piece of the index will be written.
+Either this parameter or `targetCore` must be specified.
+If this is specified, the `targetCore` parameter may not be used.
+
+`targetCore`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Multi-valued, the target Solr core to which a piece of the index will be merged.
+Either this parameter or `path` must be specified.
+If this is specified, the `path` parameter may not be used.
+
+`ranges`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A comma-separated list of hash ranges in hexadecimal format.
+If this parameter is used, `split.key` should not be.
+See the <<SPLIT Examples>> below for an example of how this parameter can be used.
+
+`split.key`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The key to be used for splitting the index.
+If this parameter is used, `ranges` should not be.
+See the <<SPLIT Examples>> below for an example of how this parameter can be used.
+
+`async`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Request ID to track this action which will be processed asynchronously.
+
+=== SPLIT Examples
+
+The `core` index will be split into as many pieces as the number of `path` or `targetCore` parameters.
+
+*Usage with two targetCore parameters*:
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2
+
+Here the `core` index will be split into two pieces and merged into the two `targetCore` indexes.
+
+*Usage with two path parameters*:
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&path=/path/to/index/1&path=/path/to/index/2
+
+The `core` index will be split into two pieces and written into the two directory paths specified.
+
+*Usage with the split.key parameter*:
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&split.key=A!
+
+Here all documents having the same route key as the `split.key` i.e., `A!` will be split from the `core` index and written to the `targetCore`.
+
+*Usage with ranges parameter*:
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2&targetCore=core3&ranges=0-1f4,1f5-3e8,3e9-5dc
+
+This example uses the `ranges` parameter with hash ranges 0-500, 501-1000 and 1001-1500 specified in hexadecimal.
+Here the index will be split into three pieces with each targetCore receiving documents matching the hash ranges specified i.e., core1 will get documents with hash range 0-500, core2 will receive documents with hash range 501-1000 and finally, core3 will receive documents with hash range 1001-1500.
+At least one hash range must be specified.
+Please note that using a single hash range equal to a route key's hash range is NOT equivalent to using the `split.key` parameter because multiple route keys can hash to the same range.
+
+The `targetCore` must already exist and must have a compatible schema with the `core` index.
+A commit is automatically called on the `core` index before it is split.
+
+This command is used as part of SolrCloud's xref:deployment-guide:shard-management.adoc#splitshard[SPLITSHARD] command but it can be used for cores in user-managed clusters as well.
+When used against a core in a user-managed cluster without `split.key` parameter, this action will split the source index and distribute its documents alternately so that each split piece contains an equal number of documents.
+If the `split.key` parameter is specified then only documents having the same route key will be split from the source index.
+
+[[coreadmin-requeststatus]]
+== REQUESTSTATUS
+
+Request the status of an already submitted asynchronous CoreAdmin API call.
+
+`admin/cores?action=REQUESTSTATUS&requestid=_id_`
+
+=== Core REQUESTSTATUS Parameters
+
+The REQUESTSTATUS command has only one parameter.
+
+`requestid`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The user defined request-id for the asynchronous request.
+
+The call below will return the status of an already submitted asynchronous CoreAdmin call.
+
+[source,bash]
+http://localhost:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=1
+
+[[coreadmin-requestrecovery]]
+== REQUESTRECOVERY
+
+The `REQUESTRECOVERY` action manually asks a core to recover by synching with the leader.
+This should be considered an "expert" level command and should be used in situations where the node (SorlCloud replica) is unable to become active automatically.
+
+`admin/cores?action=REQUESTRECOVERY&core=_core-name_`
+
+=== REQUESTRECOVERY Parameters
+
+`core`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The name of the core to re-sync.
+
+=== REQUESTRECOVERY Examples
+
+[source,bash]
+http://localhost:8981/solr/admin/cores?action=REQUESTRECOVERY&core=gettingstarted_shard1_replica1
+
+The core to specify can be found by expanding the appropriate ZooKeeper node via the admin UI.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
new file mode 100644
index 0000000..d291270
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc
@@ -0,0 +1,387 @@
+= Implicit Request Handlers
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Solr ships with many out-of-the-box request handlers, which are called implicit because they do not need to be configured in `solrconfig.xml` before you are able to use them.
+
+These handlers have pre-defined default parameters, known as _paramsets_, which can be modified if necessary.
+
+== Available Implicit Endpoints
+
+NOTE: All endpoint paths listed below should be placed after Solr's host and port (if a port is used) to construct a URL.
+
+=== Admin Handlers
+
+Many of these handlers are used throughout the Admin UI to show information about Solr.
+
+[horizontal]
+File:: Return content of files in `${solr.home}/conf/`.
+This handler must have a collection name in the path to the endpoint.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/file` |{solr-javadocs}/core/org/apache/solr/handler/admin/ShowFileRequestHandler.html[ShowFileRequestHandler] |`_ADMIN_FILE`
+|===
+
+Health:: Report the health of the node (_available only in SolrCloud mode_)
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoints |Class & Javadocs |Paramset
+|v1: `solr/admin/info/health`
+
+v2: `api/node/health` |{solr-javadocs}/core/org/apache/solr/handler/admin/HealthCheckHandler.html[HealthCheckHandler] |
+|===
++
+This endpoint also accepts additional request parameters.
+Please see {solr-javadocs}/core/org/apache/solr/handler/admin/HealthCheckHandler.html[Javadocs] for details.
+
+Logging:: Retrieve and modify registered loggers.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoints |Class & Javadocs |Paramset
+|v1: `solr/admin/info/logging`
+
+v2: `api/node/logging` |{solr-javadocs}/core/org/apache/solr/handler/admin/LoggingHandler.html[LoggingHandler] |`_ADMIN_LOGGING`
+|===
+
+Luke:: Expose the internal Lucene index.
+This handler must have a collection name in the path to the endpoint.
++
+*Documentation*: xref:indexing-guide:luke-request-handler.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/luke` |{solr-javadocs}/core/org/apache/solr/handler/admin/LukeRequestHandler.html[LukeRequestHandler] |`_ADMIN_LUKE`
+|===
+
+MBeans:: Provide info about all registered {solr-javadocs}/core/org/apache/solr/core/SolrInfoBean.html[SolrInfoMBeans].
+This handler must have a collection name in the path to the endpoint.
++
+*Documentation*: xref:deployment-guide:mbean-request-handler.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/mbeans` |{solr-javadocs}/core/org/apache/solr/handler/admin/SolrInfoMBeanHandler.html[SolrInfoMBeanHandler] |`_ADMIN_MBEANS`
+|===
+
+Ping:: Health check.
+This handler must have a collection name in the path to the endpoint.
++
+*Documentation*: xref:deployment-guide:ping.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/ping` |{solr-javadocs}/core/org/apache/solr/handler/PingRequestHandler.html[PingRequestHandler] |`_ADMIN_PING`
+|===
+
+Plugins:: Return info about all registered plugins.
+This handler must have a collection name in the path to the endpoint.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/plugins` |{solr-javadocs}/core/org/apache/solr/handler/admin/PluginInfoHandler.html[PluginInfoHandler] | None.
+|===
+
+System Properties:: Return JRE system properties.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoints |Class & Javadocs |Paramset
+|v1: `solr/admin/info/properties`
+
+v2: `api/node/properties` |{solr-javadocs}/core/org/apache/solr/handler/admin/PropertiesRequestHandler.html[PropertiesRequestHandler] |`_ADMIN_PROPERTIES`
+|===
+
+Segments:: Return info on last commit generation Lucene index segments.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/admin/segments` |{solr-javadocs}/core/org/apache/solr/handler/admin/SegmentsInfoRequestHandler.html[SegmentsInfoRequestHandler] |`_ADMIN_SEGMENTS`
+|===
+
+System Settings:: Return server statistics and settings.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoints |Class & Javadocs |Paramset
+|v1: `solr/admin/info/system`
+
+v2: `api/node/system` |{solr-javadocs}/core/org/apache/solr/handler/admin/SystemInfoHandler.html[SystemInfoHandler] |`_ADMIN_SYSTEM`
+|===
++
+This endpoint can also take the collection or core name in the path (`solr/<collection>/admin/system` or `solr/<core>/admin/system`) which will include all of the system-level information and additional information about the specific core that served the request.
+
+Threads:: Return info on all JVM threads.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoints |Class & Javadocs |Paramset
+|v1: `solr/admin/info/threads`
+
+v2: `api/node/threads` |{solr-javadocs}/core/org/apache/solr/handler/admin/ThreadDumpHandler.html[ThreadDumpHandler] |`_ADMIN_THREADS`
+|===
+
+=== Analysis Handlers
+
+[horizontal]
+Document Analysis:: Return a breakdown of the analysis process of the given document.
++
+*Documentation*: https://cwiki.apache.org/confluence/display/solr/AnalysisRequestHandler
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/analysis/document` |{solr-javadocs}/core/org/apache/solr/handler/DocumentAnalysisRequestHandler.html[DocumentAnalysisRequestHandler] |`_ANALYSIS_DOCUMENT`
+|===
+
+Field Analysis:: Return index- and query-time analysis over the given field(s)/field type(s).
+This handler drives the xref:indexing-guide:analysis-screen.adoc[] in Solr's Admin UI.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/analysis/field` |{solr-javadocs}/core/org/apache/solr/handler/FieldAnalysisRequestHandler.html[FieldAnalysisRequestHandler] |`_ANALYSIS_FIELD`
+|===
+
+=== Handlers for Configuration
+
+[horizontal]
+Config API:: Retrieve and modify Solr configuration.
++
+*Documentation*: xref:config-api.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|v1: `solr/<collection>/config`
+
+v2: `api/collections/<collection>/config` |{solr-javadocs}/core/org/apache/solr/handler/SolrConfigHandler.html[SolrConfigHandler] |`_CONFIG`
+|===
+
+Dump:: Echo the request contents back to the client.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/debug/dump` |{solr-javadocs}/core/org/apache/solr/handler/DumpRequestHandler.html[DumpRequestHandler] |`_DEBUG_DUMP`
+|===
+
+Replication:: Replicate indexes for SolrCloud recovery and user-managed cluster index distribution.
+This handler must have a core name in the path to the endpoint.
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<core>/replication` |{solr-javadocs}/core/org/apache/solr/handler/ReplicationHandler.html[ReplicationHandler] |`_REPLICATION`
+|===
+
+Schema API:: Retrieve and modify the Solr schema.
++
+*Documentation*: xref:indexing-guide:schema-api.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|v1: `solr/<collection>/schema`, `solr/<core>/schema`
+
+v2: `api/collections/<collection>/schema`, `api/cores/<core>/schema` |{solr-javadocs}/core/org/apache/solr/handler/SchemaHandler.html[SchemaHandler] |`_SCHEMA`
+|===
+
+=== Query Handlers
+
+[horizontal]
+Export:: Export full sorted result sets.
++
+*Documentation*: xref:query-guide:exporting-result-sets.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/export` |{solr-javadocs}/core/org/apache/solr/handler/ExportHandler.html[ExportHandler] |`_EXPORT`
+|===
+
+RealTimeGet:: Low-latency retrieval of the latest version of a document.
++
+*Documentation*: xref:realtime-get.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/get` |{solr-javadocs}/core/org/apache/solr/handler/RealTimeGetHandler.html[RealTimeGetHandler] |`_GET`
+|===
+
+Graph Traversal:: Return http://graphml.graphdrawing.org/[GraphML] formatted output from a `gatherNodes` streaming expression.
++
+*Documentation*: xref:query-guide:graph-traversal.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/graph` |{solr-javadocs}/core/org/apache/solr/handler/GraphHandler.html[GraphHandler] |`_ADMIN_GRAPH`
+|===
+
+SQL:: SQL query support.
++
+*Documentation*: xref:query-guide:sql-query.adoc#sql-request-handler[SQL Request Handler]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/sql` |{solr-javadocs}/core/org/apache/solr/handler/SQLHandler.html[SQLHandler] |`_SQL`
+|===
+
+Streaming Expressions:: Distributed stream processing.
++
+*Documentation*: xref:query-guide:streaming-expressions.adoc#streaming-requests-and-responses[Streaming Requests and Responses]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/stream` |{solr-javadocs}/core/org/apache/solr/handler/StreamHandler.html[StreamHandler] |`_STREAM`
+|===
+
+Terms:: Return a field's indexed terms and the number of documents containing each term.
++
+*Documentation*: xref:query-guide:terms-component.adoc#using-the-terms-component-in-a-request-handler[Using the Terms Component in a Request Handler]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/terms` |{solr-javadocs}/core/org/apache/solr/handler/component/SearchHandler.html[SearchHandler] |`_TERMS`
+|===
+
+=== Update Handlers
+
+[horizontal]
+Update:: Add, delete and update indexed documents formatted as SolrXML, CSV, SolrJSON or javabin.
++
+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/update` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE`
+|===
+
+CSV Updates:: Add and update CSV-formatted documents.
++
+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc#csv-update-convenience-paths[CSV Update Convenience Paths]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/update/csv` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_CSV`
+|===
+
+JSON Updates:: Add, delete and update SolrJSON-formatted documents.
++
+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc#json-update-convenience-paths[JSON Update Convenience Paths]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/update/json` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_JSON`
+|===
+
+Custom JSON Updates:: Add and update custom JSON-formatted documents.
++
+*Documentation*: xref:indexing-guide:transforming-and-indexing-custom-json.adoc[]
++
+[cols="3*.",frame=none,grid=cols,options="header"]
+|===
+|API Endpoint |Class & Javadocs |Paramset
+|`solr/<collection>/update/json/docs` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_JSON_DOCS`
+|===
+
+== How to View Implicit Handler Paramsets
+
+You can see configuration for all request handlers, including the implicit request handlers, via the xref:config-api.adoc[].
+
+To include the expanded paramset in the response, as well as the effective parameters from merging the paramset parameters with the built-in parameters, use the `expandParams` request parameter.
+
+For example, for the `/export` request handler, you can make a request like this:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1expandparams]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/gettingstarted/config/requestHandler?componentName=/export&expandParams=true
+----
+====
+
+[example.tab-pane#v2expandparams]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+http://localhost:8983/api/collections/gettingstarted/config/requestHandler?componentName=/export&expandParams=true
+----
+====
+--
+
+The response will look similar to:
+
+[source,json]
+----
+{
+ "config": {
+ "requestHandler": {
+ "/export": {
+ "class": "solr.ExportHandler",
+ "useParams": "_EXPORT",
+ "components": ["query"],
+ "defaults": {
+ "wt": "json"
+ },
+ "invariants": {
+ "rq": "{!xport}",
+ "distrib": false
+ },
+ "name": "/export",
+ "_useParamsExpanded_": {
+ "_EXPORT": "[NOT AVAILABLE]"
+ },
+ "_effectiveParams_": {
+ "distrib": "false",
+ "omitHeader": "true",
+ "wt": "json",
+ "rq": "{!xport}"
+ }
+ }
+ }
+ }
+}
+----
+
+== How to Edit Implicit Handler Paramsets
+
+Because implicit request handlers are not present in `solrconfig.xml`, configuration of their associated `default`, `invariant` and `appends` parameters may be edited via the xref:request-parameters-api.adoc[] using the paramset listed in the above table.
+However, other parameters, including SearchHandler components, may not be modified.
+The invariants and appends specified in the implicit configuration cannot be overridden.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/index-location-format.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/index-location-format.adoc
new file mode 100644
index 0000000..f577db4
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/index-location-format.adoc
@@ -0,0 +1,65 @@
+= Index Location and Format
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Where and how Solr stores its indexes are configurable options.
+
+== Specifying a Location for Index Data with the dataDir Parameter
+
+By default, Solr stores its index data in a directory called `/data` under the core's instance directory (`instanceDir`).
+If you would like to specify a different directory for storing index data, you can configure the `dataDir` in the `core.properties` file for the core, or use the `<dataDir>` parameter in the `solrconfig.xml` file.
+You can specify another directory either with an absolute path or a pathname relative to the instanceDir of the SolrCore.
+For example:
+
+[source,xml]
+----
+<dataDir>/solr/data/${solr.core.name}</dataDir>
+----
+
+The `${solr.core.name}` substitution will cause the name of the current core to be substituted, which results in each core's data being kept in a separate subdirectory.
+
+If you are using xref:deployment-guide:user-managed-index-replication.adoc[] to replicate the Solr index, then the `<dataDir>` directory should correspond to the index directory used in the replication configuration.
+
+NOTE: If the environment variable `SOLR_DATA_HOME` is defined, or if `solr.data.home` is configured for your DirectoryFactory, or if `solr.xml` contains an
+element `<solrDataHome>` then the location of data directory will be `<SOLR_DATA_HOME>/<instance_name>/data`.
+
+== Specifying the DirectoryFactory For Your Index
+
+The default {solr-javadocs}/core/org/apache/solr/core/NRTCachingDirectoryFactory.html[`solr.NRTCachingDirectoryFactory`] is filesystem based, and tries to pick the best implementation for the current JVM and platform.
+You can force a particular implementation and/or configuration options by specifying {solr-javadocs}/core/org/apache/solr/core/MMapDirectoryFactory.html[`solr.MMapDirectoryFactory`] or {solr-javadocs}/core/org/apache/solr/core/NIOFSDirectoryFactory.html[`solr.NIOFSDirectoryFactory`].
+
+[source,xml]
+----
+<directoryFactory name="DirectoryFactory"
+ class="solr.MMapDirectoryFactory">
+ <bool name="preload">true</bool>
+</directoryFactory>
+----
+
+The {solr-javadocs}/core/org/apache/solr/core/RAMDirectoryFactory.html[`solr.RAMDirectoryFactory`] is memory based, not persistent, and does not work with replication.
+Use this DirectoryFactory to store your index in RAM.
+
+[source,xml]
+----
+<directoryFactory class="org.apache.solr.core.RAMDirectoryFactory"/>
+----
+
+[NOTE]
+====
+If you are using Hadoop and would like to store your indexes in HDFS, you should use the {solr-javadocs}/modules/hdfs/org/apache/solr/core/HdfsDirectoryFactory.html[`solr.HdfsDirectoryFactory`] instead of either of the above implementations.
+For more details, see the section xref:deployment-guide:solr-on-hdfs.adoc[].
+====
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/index-segments-merging.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/index-segments-merging.adoc
new file mode 100644
index 0000000..9bf7cb4
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/index-segments-merging.adoc
@@ -0,0 +1,380 @@
+= Index Segments and Merging
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Lucene indexes are stored in segments and Solr offers several parameters to control how new segments are written and when segments are merged.
+
+Lucene indexes are "write-once" files: once a segment has been written to permanent storage (to disk), it is never altered.
+This means that indexes are actually comprised of several files which are each subsets of the full index.
+In order to prevent eternal fragmentation of the index, segments are periodically merged.
+
+== <indexConfig> in solrconfig.xml
+
+The `<indexConfig>` section of `solrconfig.xml` defines low-level behavior of the Lucene index writers.
+
+By default, the settings are commented out in the sample `solrconfig.xml` included with Solr, which means the defaults are used.
+In most cases, the defaults are fine.
+
+[source,xml]
+----
+<indexConfig>
+ ...
+</indexConfig>
+----
+
+== Writing New Segments
+
+The following elements can be defined under the `<indexConfig>` element and define when new segments are written ("flushed") to disk.
+
+=== ramBufferSizeMB
+
+Once accumulated document updates exceed this much memory space (defined in megabytes), then the pending updates are flushed.
+This can also create new segments or trigger a merge.
+Using this setting is generally preferable to `maxBufferedDocs`.
+If both `maxBufferedDocs` and `ramBufferSizeMB` are set in `solrconfig.xml`, then a flush will occur when either limit is reached.
+The default is `100` MB.
+
+[source,xml]
+----
+<ramBufferSizeMB>100</ramBufferSizeMB>
+----
+
+=== maxBufferedDocs
+
+Sets the number of document updates to buffer in memory before they are flushed as a new segment.
+This may also trigger a merge.
+The default Solr configuration sets to flush by RAM usage (`ramBufferSizeMB`).
+
+[source,xml]
+----
+<maxBufferedDocs>1000</maxBufferedDocs>
+----
+
+=== useCompoundFile
+
+Controls whether newly written (and not yet merged) index segments should use the <<Compound File Segments>> format.
+The default is `false`.
+
+[source,xml]
+----
+<useCompoundFile>false</useCompoundFile>
+----
+
+=== ramPerThreadHardLimitMB
+
+Sets the maximum memory (defined in megabytes) consumption per thread triggering a forced flush if exceeded.
+The given value must be greater than `0` and less than `2048` MB (2GB).
+
+[source,xml]
+----
+<ramPerThreadHardLimitMB>1945</ramPerThreadHardLimitMB>
+----
+
+NOTE: This is an expert level parameter as it triggers forced flush even if `ramBufferSizeMB` has not been exceeded.
+
+== Merging Index Segments
+
+The following settings define when segments are merged.
+
+=== mergePolicyFactory
+
+Defines how merging segments is done.
+
+The default in Solr is to use `TieredMergePolicy`, which merges segments of approximately equal size, subject to an allowed number of segments per tier.
+
+Other policies available are the `LogByteSizeMergePolicy` and `LogDocMergePolicy`.
+For more information on these policies, please see {lucene-javadocs}/core/org/apache/lucene/index/MergePolicy.html[the MergePolicy javadocs].
+
+[source,xml]
+----
+<mergePolicyFactory class="org.apache.solr.index.TieredMergePolicyFactory">
+ <int name="maxMergeAtOnce">10</int>
+ <int name="segmentsPerTier">10</int>
+ <double name="forceMergeDeletesPctAllowed">10.0</double>
+ <double name="deletesPctAllowed">33.0</double>
+</mergePolicyFactory>
+----
+
+[[merge-factors]]
+=== Controlling Segment Sizes
+
+The most common adjustment users make to the configuration of `TieredMergePolicy` (or `LogByteSizeMergePolicy`) are the "merge factors" to change how many segments should be merged at one time and, in the `TieredMergePolicy` case, the maximum size of an merged segment.
+
+For `TieredMergePolicy`, this is controlled by setting the `maxMergeAtOnce` (default `10`), `segmentsPerTier` (default `10`) and `maxMergedSegmentMB` (default `5000`) options.
+
+`LogByteSizeMergePolicy` has a single `mergeFactor` option (default `10`).
+
+To understand why these options are important, consider what happens when an update is made to an index using `LogByteSizeMergePolicy`: Documents are always added to the most recently opened segment.
+When a segment fills up, a new segment is created and subsequent updates are placed there.
+
+If creating a new segment would cause the number of lowest-level segments to exceed the `mergeFactor` value, then all those segments are merged together to form a single large segment.
+Thus, if the merge factor is `10`, each merge results in the creation of a single segment that is roughly ten times larger than each of its ten constituents.
+When there are 10 of these larger segments, then they in turn are merged into an even larger single segment.
+This process can continue indefinitely.
+
+When using `TieredMergePolicy`, the process is the same, but instead of a single `mergeFactor` value, the `segmentsPerTier` setting is used as the threshold to decide if a merge should happen, and the `maxMergeAtOnce` setting determines how many segments should be included in the merge.
+
+Choosing the best merge factors is generally a trade-off of indexing speed vs. searching speed.
+Having fewer segments in the index generally accelerates searches, because there are fewer places to look.
+It also can also result in fewer physical files on disk.
+But to keep the number of segments low, merges will occur more often, which can add load to the system and slow down updates to the index.
+
+Conversely, keeping more segments can accelerate indexing, because merges happen less often, making an update is less likely to trigger a merge.
+But searches become more computationally expensive and will likely be slower, because search terms must be looked up in more index segments.
+Faster index updates also means shorter commit turnaround times, which means more timely search results.
+
+=== Controlling Deleted Document Percentages
+
+When a document is deleted or updated, the document is marked as deleted but it not removed from the index until the segment is merged.
+There are two parameters that can can be adjusted when using the default `TieredMergePolicy` that influence the number of deleted documents in an index.
+
+`forceMergeDeletesPctAllowed`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `10.0`
+|===
++
+When the external `expungeDeletes` command is issued, any segment that has more than this percent deleted documents will be merged into a new segment and the data associated with the deleted documents will be purged.
+A value of `0.0` will make expungeDeletes behave essentially identically to `optimize`.
+
+`deletesPctAllowed`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `33.0`
+|===
++
+During normal segment merging, a best effort is made to insure that the total percentage of deleted documents in the index is below this threshold.
+Valid settings are between 20% and 50%.
+33% was chosen as the default because as this setting approaches 20%, considerable load is added to the system.
+
+=== Customizing Merge Policies
+
+If the configuration options for the built-in merge policies do not fully suit your use case, you can customize them either by creating a custom merge policy factory that you specify in your configuration, or by configuring a {solr-javadocs}/core/org/apache/solr/index/WrapperMergePolicyFactory.html[merge policy wrapper] which uses a `wrapped.prefix` configuration option to control how the factory it wraps will be configured:
+
+[source,xml]
+----
+<mergePolicyFactory class="org.apache.solr.index.SortingMergePolicyFactory">
+ <str name="sort">timestamp desc</str>
+ <str name="wrapped.prefix">inner</str>
+ <str name="inner.class">org.apache.solr.index.TieredMergePolicyFactory</str>
+ <int name="inner.maxMergeAtOnce">10</int>
+ <int name="inner.segmentsPerTier">10</int>
+</mergePolicyFactory>
+----
+
+The example above shows Solr's {solr-javadocs}/core/org/apache/solr/index/SortingMergePolicyFactory.html[`SortingMergePolicyFactory`] being configured to sort documents in merged segments by `"timestamp desc"`, and wrapped around a `TieredMergePolicyFactory` configured to use the values `maxMergeAtOnce=10` and `segmentsPerTier=10` via the `inner` prefix defined by `SortingMergePolicyFactory` 's `wrapped.prefix` option.
+For more information on using `SortingMergePolicyFactory`, see xref:query-guide:common-query-parameters.adoc#segmentterminateearly-parameter[the segmentTerminateEarly parameter].
+
+=== mergeScheduler
+
+The merge scheduler controls how merges are performed.
+The default `ConcurrentMergeScheduler` performs merges in the background using separate threads.
+The alternative, `SerialMergeScheduler`, does not perform merges with separate threads.
+
+The `ConcurrentMergeScheduler` has the following configurable attributes.
+The defaults for these attributes are dynamically set based on whether the underlying disk drive is rotational disk or not.
+Refer to xref:deployment-guide:taking-solr-to-production.adoc#dynamic-defaults-for-concurrentmergescheduler[Dynamic Defaults for ConcurrentMergeScheduler] for more details.
+
+`maxMergeCount`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum number of simultaneous merges that are allowed.
+If a merge is necessary yet we already have this many threads running, the indexing thread will block until a merge thread has completed.
+Note that Solr will only run the smallest `maxThreadCount` merges at a time.
+
+`maxThreadCount`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum number of simultaneous merge threads that should be running at once.
+This must be less than `maxMergeCount`.
+
+`ioThrottle`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A Boolean value (`true` or `false`) to explicitly control I/O throttling.
+By default throttling is enabled and the CMS will limit I/O throughput when merging to leave other (search, indexing) some room.
+
+.Example: Dynamic defaults
+[source,xml]
+----
+<mergeScheduler class="org.apache.lucene.index.ConcurrentMergeScheduler"/>
+----
+
+.Example: Explicit defaults
+[source,xml]
+----
+<mergeScheduler class="org.apache.lucene.index.ConcurrentMergeScheduler">
+ <int name="maxMergeCount">9</int>
+ <int name="maxThreadCount">4</int>
+</mergeScheduler>
+----
+
+=== mergedSegmentWarmer
+
+When using Solr for xref:deployment-guide:solrcloud-distributed-requests.adoc#near-real-time-nrt-use-cases[Near Real Time Use Cases], a merged segment warmer can be configured to warm the reader on the newly merged segment, before the merge commits.
+This is not required for near real-time search, but will reduce search latency on opening a new near real-time reader after a merge completes.
+
+[source,xml]
+----
+<mergedSegmentWarmer class="org.apache.lucene.index.SimpleMergedSegmentWarmer"/>
+----
+
+== Compound File Segments
+
+Each Lucene segment is typically comprised of a dozen or so files.
+Lucene can be configured to bundle all of the files for a segment into a single compound file using a file extension of `.cfs`, for "Compound File Segment".
+
+CFS segments may incur a minor performance hit for various reasons, depending on the runtime environment.
+For example, filesystem buffers are typically associated with open file descriptors, which may limit the total cache space available to each index.
+
+On systems where the number of open files allowed per process is limited, CFS may avoid hitting that limit.
+The open files limit might also be tunable for your OS with the Linux/Unix `ulimit` command, or something similar for other operating systems.
+
+.CFS: New Segments vs Merged Segments
+[NOTE]
+====
+To configure whether _newly written segments_ should use CFS, see the <<usecompoundfile,`useCompoundFile`>> setting described above.
+To configure whether _merged segments_ use CFS, review the Javadocs for your <<mergepolicyfactory,`mergePolicyFactory`>>.
+
+Many <<Merging Index Segments,Merge Policy>> implementations support `noCFSRatio` and `maxCFSSegmentSizeMB` settings with default values that prevent compound files from being used for large segments, but do use compound files for small segments.
+====
+
+== Segments Info Screen
+
+The Segments Info screen in the Admin UI lets you see a visualization of the various segments in the underlying Lucene index for this core, with information about the size of each segment – both bytes and in number of documents – as well as other basic metadata about those segments.
+Most visible is the number of deleted documents, but you can hover your mouse over the segments to see additional numeric details.
+
+image::index-segments-merging/segments_info.png[image,width=486,height=250]
+
+This information may be useful for people to help make decisions about the optimal <<merging-index-segments,merge settings>> for their data.
+
+== Index Locks
+
+=== lockType
+
+The LockFactory options specify the locking implementation to use.
+
+The set of valid lock type options depends on the xref:index-location-format.adoc[DirectoryFactory] you have configured.
+
+The values listed below are are supported by `StandardDirectoryFactory` (the default):
+
+* `native` (default) uses `NativeFSLockFactory` to specify native OS file locking.
+If a second Solr process attempts to access the directory, it will fail.
+Do not use when multiple Solr web applications are attempting to share a single index.
+See also the {lucene-javadocs}/core/org/apache/lucene/store/NativeFSLockFactory.html[NativeFSLockFactory javadocs].
+
+* `simple` uses `SimpleFSLockFactory` to specify a plain file for locking.
+See also the {lucene-javadocs}/core/org/apache/lucene/store/SimpleFSLockFactory.html[SimpleFSLockFactory javadocs].
+
+* `single` (expert) uses `SingleInstanceLockFactory`.
+Use for special situations of a read-only index directory, or when there is no possibility of more than one process trying to modify the index (even sequentially).
+This type will protect against multiple cores within the _same_ JVM attempting to access the same index.
++
+WARNING: If multiple Solr instances in different JVMs modify an index, this type will _not_ protect against index corruption.
+
++
+See also the {lucene-javadocs}/core/org/apache/lucene/store/SingleInstanceLockFactory.html[SingleInstanceLockFactory javadocs].
+
+* `hdfs` uses `HdfsLockFactory` to support reading and writing index and transaction log files to a HDFS filesystem.
+See the section xref:deployment-guide:solr-on-hdfs.adoc[] for more details on using this feature.
+
+[source,xml]
+----
+<lockType>native</lockType>
+----
+
+=== writeLockTimeout
+
+The maximum time to wait for a write lock on an IndexWriter.
+The default is `1000`, expressed in milliseconds.
+
+[source,xml]
+----
+<writeLockTimeout>1000</writeLockTimeout>
+----
+
+== Other Indexing Settings
+
+There are a few other parameters that may be important to configure for your implementation.
+These settings affect how or when updates are made to an index.
+
+=== deletionPolicy
+
+Controls how commits are retained in case of rollback.
+The default is `SolrDeletionPolicy`, which take ths following parameters:
+
+`maxCommitsToKeep`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum number of commits to keep.
+
+`maxOptimizedCommitsToKeep`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum number of optimized commits to keep.
+
+`maxCommitAge`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The maximum age of any commit to keep.
+This supports `DateMathParser` syntax.
+
+[source,xml]
+----
+<deletionPolicy class="solr.SolrDeletionPolicy">
+ <str name="maxCommitsToKeep">1</str>
+ <str name="maxOptimizedCommitsToKeep">0</str>
+ <str name="maxCommitAge">1DAY</str>
+</deletionPolicy>
+----
+
+=== infoStream
+
+The InfoStream setting instructs the underlying Lucene classes to write detailed debug information from the indexing process as Solr log messages.
+Note that enabling this may substantially increase the size of your logs and can cause some performance lags in high traffic systems.
+The default is `false`.
+
+[source,xml]
+----
+<infoStream>false</infoStream>
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/initparams.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/initparams.adoc
new file mode 100644
index 0000000..31e8a5e
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/initparams.adoc
@@ -0,0 +1,137 @@
+= InitParams
+:page-show-toc: false
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The `<initParams>` section of `solrconfig.xml` allows you to define request handler parameters outside of the handler configuration.
+
+There are a couple of use cases where this might be desired:
+
+* Some handlers are implicitly defined in code (see xref:implicit-requesthandlers.adoc[]) and there should be a way to add, append, or override some of the implicitly defined properties.
+* There are a few properties that are used across handlers.
+This helps you keep only a single definition of those properties and apply them over multiple handlers.
+
+For example, if you want several of your search handlers to return the same list of fields, you can create an `<initParams>` section without having to define the same set of parameters in each request handler definition.
+If you have a single request handler that should return different fields, you can define the overriding parameters in individual `<requestHandler>` sections as usual.
+
+The properties and configuration of an `<initParams>` section mirror the properties and configuration of a request handler.
+It can include sections for defaults, appends, and invariants, the same as any request handler.
+
+For example, here is one of the `<initParams>` sections defined by default in the `_default` example:
+
+[source,xml]
+----
+<initParams path="/update/**,/query,/select,/tvrh,/elevate,/spell">
+ <lst name="defaults">
+ <str name="df">_text_</str>
+ </lst>
+</initParams>
+----
+
+This sets the default search field ("df") to be "_text_" for all of the request handlers named in the path section.
+If we later want to change the `/query` request handler to search a different field by default, we could override the `<initParams>` by defining the parameter in the `<requestHandler>` section for `/query`.
+
+The syntax and semantics are similar to that of a `<requestHandler>`.
+The following are the attributes:
+
+`path`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A comma-separated list of paths which will use the parameters.
+Wildcards can be used in paths to define nested paths, as described below.
+
+`name`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+The name of this set of parameters.
+The name can be used directly in a requestHandler definition if a path is not explicitly named.
+If you give your `<initParams>` a name, you can refer to the parameters in a `<requestHandler>` that is not defined as a path.
++
+For example, if an `<initParams>` section has the name "myParams", you can call the name when defining your request handler:
++
+[source,xml]
+<requestHandler name="/dump1" class="DumpRequestHandler" initParams="myParams"/>
+
+== Wildcards in initParams
+
+An `<initParams>` section can support wildcards to define nested paths that should use the parameters defined.
+A single asterisk (`\*`) denotes that a nested path one level deeper should use the parameters.
+Double asterisks (`**`) denote all nested paths no matter how deep should use the parameters.
+
+For example, if we have an `<initParams>` that looks like this:
+
+[source,xml]
+----
+<initParams name="myParams" path="/myhandler,/root/*,/root1/**">
+ <lst name="defaults">
+ <str name="fl">_text_</str>
+ </lst>
+ <lst name="invariants">
+ <str name="rows">10</str>
+ </lst>
+ <lst name="appends">
+ <str name="df">title</str>
+ </lst>
+</initParams>
+----
+
+We've defined three paths in the first line of the example:
+
+* `/myhandler` declared as a direct path.
+* `/root/*` with a single asterisk to indicate the parameters should apply to paths that are one level deep.
+* `/root1/**` with double asterisks to indicate the parameters should apply to all nested paths, no matter how deep.
+
+When we define the request handlers, the wildcards will work in the following ways:
+
+[source,xml]
+----
+<requestHandler name="/myhandler" class="SearchHandler"/>
+----
+
+The `/myhandler` class was named as a path in the `<initParams>` so this will use those parameters.
+
+Next we have a request handler named `/root/search5`:
+
+[source,xml]
+----
+<requestHandler name="/root/search5" class="SearchHandler"/>
+----
+
+We defined a wildcard for nested paths that are one level deeper than `/root`, so this request handler will use the parameters.
+This one, however, will not, because `/root/search5/test` is more than one level deep from `/root`:
+
+[source,xml]
+----
+<requestHandler name="/root/search5/test" class="SearchHandler"/>
+----
+
+If we want to define all levels of nested paths, we should use double asterisks, as in the example path `/root1/**`:
+
+[source,xml]
+----
+<requestHandler name="/root1/search/tests" class="SearchHandler"/>
+----
+
+Any path under `/root1`, whether explicitly defined in a request handler or not, will use the parameters defined in the matching `initParams` section.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/libs.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/libs.adoc
new file mode 100644
index 0000000..db651e2
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/libs.adoc
@@ -0,0 +1,75 @@
+= Lib Directories and Directives
+
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Here we describe two simple and effective methods to make the `.jar` files for Solr plugins visible to Solr.
+
+Such files are sometimes called "libraries" or "libs" for short.
+Essentially you can put them in some special places or explicitly tell Solr about them from your config.
+
+If there is overlap or inter-dependencies between libraries, then pay attention to the order. You can think of it like a stack that is searched top-down. At the top are the lib directives in reverse order, then Solr core's lib, then Solr home's lib, then Solr itself.
+
+== Lib Directories
+
+There are several special places you can place Solr plugin `.jar` files:
+
+* `<solr_home>/lib/`: The `.jar` files placed here are available to all Solr cores running on the node, and to node level plugins referenced in `solr.xml` -- so basically everything.
+This directory is not present by default so create it.
+See xref:deployment-guide:taking-solr-to-production.adoc[].
+
+* `<core_instance>/lib/`: In a user-managed cluster or a single-node installation, you may want to add plugins just for a specific Solr core.
+Create this adjacent to the `conf/` directory; it's not present by default.
+
+* `<solr_install>/server/solr-webapp/webapp/WEB-INF/lib/`: The `.jar` files for Solr itself and it's dependencies live here.
+Certain plugins or add-ons to plugins require placement here.
+They will document themselves to say so.
+
+* `<solr_install>/server/lib/ext`: The `.jar` files used for the Solr server as well as Solr Core/SolrJ.
+
+Solr incorporates Jetty for providing HTTP server functionality.
+Jetty has some directories that contain `.jar` files for itself and its own plugins / modules or JVM level plugins (e.g., loggers).
+Solr plugins won't work in these locations.
+
+== Lib Directives in SolrConfig
+
+_Both_ plugin and xref:resource-loading.adoc[resource] file paths are configurable via `<lib/>` directives in `solrconfig.xml`.
+When a directive matches a directory, then resources can be resolved from it.
+When a directive matches a `.jar` file, Solr plugins and their dependencies are resolved from it.
+Resources can be placed in a `.jar` too but that's unusual.
+It's erroneous to refer to any other type of file.
+
+A `<lib/>` directive must have one (not both) of these two attributes:
+
+* `path`: used to refer to a single directory (for resources) or file (for a plugin `.jar`)
+
+* `dir`: used to refer to _all_ direct descendants of the specified directory. Optionally supply a `regex` attribute to filter these to those matching the regular expression.
+
+All directories are resolved as relative to the Solr core's `instanceDir`.
+
+These examples show how to load modules into Solr:
+
+[source,xml]
+----
+ <lib dir="${solr.install.dir:../../../..}/modules/extraction/lib" regex=".*\.jar" />
+
+ <lib dir="${solr.install.dir:../../../..}/modules/clustering/lib/" regex=".*\.jar" />
+
+ <lib dir="${solr.install.dir:../../../..}/modules/langid/lib/" regex=".*\.jar" />
+
+ <lib dir="${solr.install.dir:../../../..}/modules/ltr/lib/" regex=".*\.jar" />
+----
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/managed-resources.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/managed-resources.adoc
new file mode 100644
index 0000000..7bcd165
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/managed-resources.adoc
@@ -0,0 +1,314 @@
+= Managed Resources
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Managed resources expose a REST API endpoint for performing Create-Read-Update-Delete (CRUD) operations on a Solr object.
+
+Any long-lived Solr object that has configuration settings and/or data is a good candidate to be a managed resource.
+Managed resources complement other programmatically manageable components in Solr, such as the RESTful schema API to add fields to a managed schema.
+
+Consider a Web-based UI that offers Solr-as-a-Service where users need to configure a set of stop words and synonym mappings as part of an initial setup process for their search application.
+This type of use case can easily be supported using the Managed Stop Filter & Managed Synonym Graph Filter Factories provided by Solr, via the Managed resources REST API.
+
+Users can also write their own custom plugins, that leverage the same internal hooks to make additional resources REST managed.
+
+All of the examples in this section assume you are running the "techproducts" Solr example:
+
+[source,bash]
+----
+bin/solr -e techproducts
+----
+
+== Managed Resources Overview
+
+Let's begin learning about managed resources by looking at a couple of examples provided by Solr for managing stop words and synonyms using a REST API.
+After reading this section, you'll be ready to dig into the details of how managed resources are implemented in Solr so you can start building your own implementation.
+
+=== Managing Stop Words
+
+To begin, you need to define a field type that uses the xref:indexing-guide:filters.adoc#managed-stop-filter[ManagedStopFilterFactory], such as:
+
+[source,xml,subs="verbatim,callouts"]
+----
+<fieldType name="managed_en" positionIncrementGap="100">
+ <analyzer>
+ <tokenizer class="solr.StandardTokenizerFactory"/>
+ <filter class="solr.ManagedStopFilterFactory" <!--1-->
+ managed="english" /> <!--2-->
+ </analyzer>
+</fieldType>
+----
+
+There are two important things to notice about this field type definition:
+
+<1> The filter implementation class is `solr.ManagedStopFilterFactory`.
+This is a special implementation of the xref:indexing-guide:filters.adoc#stop-filter[StopFilterFactory] that uses a set of stop words that are managed from a REST API.
+
+<2> The `managed=”english”` attribute gives a name to the set of managed stop words, in this case indicating the stop words are for English text.
+
+The REST endpoint for managing the English stop words in the techproducts collection is: `/solr/techproducts/schema/analysis/stopwords/english`.
+
+The example resource path should be mostly self-explanatory.
+It should be noted that the ManagedStopFilterFactory implementation determines the `/schema/analysis/stopwords` part of the path, which makes sense because this is an analysis component defined by the schema.
+
+It follows that a field type that uses the following filter:
+
+[source,xml]
+----
+<filter class="solr.ManagedStopFilterFactory"
+ managed="french" />
+----
+
+would resolve to path: `/solr/techproducts/schema/analysis/stopwords/french`.
+
+So now let’s see this API in action, starting with a simple GET request:
+
+[source,bash]
+----
+curl "http://localhost:8983/solr/techproducts/schema/analysis/stopwords/english"
+----
+
+Assuming you sent this request to Solr, the response body is a JSON document:
+
+[source,json]
+----
+{
+ "responseHeader":{
+ "status":0,
+ "QTime":1
+ },
+ "wordSet":{
+ "initArgs":{"ignoreCase":true},
+ "initializedOn":"2014-03-28T20:53:53.058Z",
+ "managedList":[
+ "a",
+ "an",
+ "and",
+ "are",
+ ]
+ }
+}
+----
+
+The `sample_techproducts_configs` xref:config-sets.adoc[configset] ships with a pre-built set of managed stop words, however you should only interact with this file using the API and not edit it directly.
+
+One thing that should stand out to you in this response is that it contains a `managedList` of words as well as `initArgs`.
+This is an important concept in this framework -- managed resources typically have configuration and data.
+For stop words, the only configuration parameter is a boolean that determines whether to ignore the case of tokens during stop word filtering (ignoreCase=true|false).
+The data is a list of words, which is represented as a JSON array named `managedList` in the response.
+
+Now, let’s add a new word to the English stop word list using an HTTP PUT:
+
+[source,bash]
+----
+curl -X PUT -H 'Content-type:application/json' --data-binary '["foo"]' "http://localhost:8983/solr/techproducts/schema/analysis/stopwords/english"
+----
+
+Here we’re using curl to PUT a JSON list containing a single word “foo” to the managed English stop words set.
+Solr will return 200 if the request was successful.
+You can also put multiple words in a single PUT request.
+
+You can test to see if a specific word exists by sending a GET request for that word as a child resource of the set, such as:
+
+[source,bash]
+----
+curl "http://localhost:8983/solr/techproducts/schema/analysis/stopwords/english/foo"
+----
+
+This request will return a status code of 200 if the child resource (foo) exists or 404 if it does not exist the managed list.
+
+To delete a stop word, you would do:
+
+[source,bash]
+----
+curl -X DELETE "http://localhost:8983/solr/techproducts/schema/analysis/stopwords/english/foo"
+----
+
+NOTE: PUT/POST is used to add terms to an existing list instead of replacing the list entirely.
+This is because it is more common to add a term to an existing list than it is to replace a list altogether, so the API favors the more common approach of incrementally adding terms especially since deleting individual terms is also supported.
+
+=== Managing Synonyms
+
+For the most part, the API for managing synonyms behaves similar to the API for stop words, except instead of working with a list of words, it uses a map, where the value for each entry in the map is a set of synonyms for a term.
+As with stop words, the `sample_techproducts_configs` xref:config-sets.adoc[configset] includes a pre-built set of synonym mappings suitable for the sample data that is activated by the following field type definition:
+
+[source,xml]
+----
+<fieldType name="managed_en" positionIncrementGap="100">
+ <analyzer type="index">
+ <tokenizer class="solr.StandardTokenizerFactory"/>
+ <filter class="solr.ManagedStopFilterFactory" managed="english" />
+ <filter class="solr.ManagedSynonymGraphFilterFactory" managed="english" />
+ <filter class="solr.FlattenGraphFilterFactory"/> <!-- required on index analyzers after graph filters -->
+ </analyzer>
+ <analyzer type="query">
+ <tokenizer class="solr.StandardTokenizerFactory"/>
+ <filter class="solr.ManagedStopFilterFactory" managed="english" />
+ <filter class="solr.ManagedSynonymGraphFilterFactory" managed="english" />
+ </analyzer>
+</fieldType>
+----
+
+To get the map of managed synonyms, send a GET request to:
+
+[source,bash]
+----
+curl "http://localhost:8983/solr/techproducts/schema/analysis/synonyms/english"
+----
+
+This request will return a response that looks like:
+
+[source,json]
+----
+{
+ "responseHeader":{
+ "status":0,
+ "QTime":3},
+ "synonymMappings":{
+ "initArgs":{
+ "ignoreCase":true,
+ "format":"solr"},
+ "initializedOn":"2014-12-16T22:44:05.33Z",
+ "managedMap":{
+ "GB":
+ ["GiB",
+ "Gigabyte"],
+ "TV":
+ ["Television"],
+ "happy":
+ ["glad",
+ "joyful"]}}}
+----
+
+Managed synonyms are returned under the `managedMap` property which contains a JSON Map where the value of each entry is a set of synonyms for a term, such as "happy" has synonyms "glad" and "joyful" in the example above.
+
+To add a new synonym mapping, you can PUT/POST a single mapping such as:
+
+[source,bash]
+----
+curl -X PUT -H 'Content-type:application/json' --data-binary '{"mad":["angry","upset"]}' "http://localhost:8983/solr/techproducts/schema/analysis/synonyms/english"
+----
+
+The API will return status code 200 if the PUT request was successful.
+To determine the synonyms for a specific term, you send a GET request for the child resource, such as `/schema/analysis/synonyms/english/mad` would return `["angry","upset"]`.
+
+You can also PUT a list of symmetric synonyms, which will be expanded into a mapping for each term in the list.
+For example, you could PUT the following list of symmetric synonyms using the JSON list syntax instead of a map:
+
+[source,bash]
+----
+curl -X PUT -H 'Content-type:application/json' --data-binary '["funny", "entertaining", "whimiscal", "jocular"]' "http://localhost:8983/solr/techproducts/schema/analysis/synonyms/english"
+----
+
+Note that the expansion is performed when processing the PUT request so the underlying persistent state is still a managed map.
+Consequently, if after sending the previous PUT request, you did a GET for `/schema/analysis/synonyms/english/jocular`, then you would receive a list containing `["funny", "entertaining", "whimiscal"]`.
+Once you've created synonym mappings using a list, each term must be managed separately.
+
+Lastly, you can delete a mapping by sending a DELETE request to the managed endpoint.
+
+== Applying Managed Resource Changes
+
+Changes made to managed resources via this REST API are not applied to the active Solr components until the Solr collection (or Solr core in single server mode) is reloaded.
+
+For example: after adding or deleting a stop word, you must reload the core/collection before changes become active; related APIs: xref:coreadmin-api.adoc[] and xref:collections-api.adoc[].
+
+This approach is required when running in distributed mode so that we are assured changes are applied to all cores in a collection at the same time so that behavior is consistent and predictable.
+It goes without saying that you don’t want one of your replicas working with a different set of stop words or synonyms than the others.
+
+One subtle outcome of this _apply-changes-at-reload_ approach is that the once you make changes with the API, there is no way to read the active data.
+In other words, the API returns the most up-to-date data from an API perspective, which could be different than what is currently being used by Solr components.
+
+However, the intent of this API implementation is that changes will be applied using a reload within a short time frame after making them so the time in which the data returned by the API differs from what is active in the server is intended to be negligible.
+
+[IMPORTANT]
+====
+Changing things like stop words and synonym mappings typically require reindexing existing documents if being used by index-time analyzers.
+The RestManager framework does not guard you from this, it simply makes it possible to programmatically build up a set of stop words, synonyms, etc.
+See the section xref:indexing-guide:reindexing.adoc[] for more information about reindexing your documents.
+====
+
+== RestManager Endpoint
+
+Metadata about registered ManagedResources is available using the `/schema/managed` endpoint for each collection.
+
+Assuming you have the `managed_en` field type shown above defined in your schema, sending a GET request to the following resource will return metadata about which schema-related resources are being managed by the RestManager:
+
+[source,bash]
+----
+curl "http://localhost:8983/solr/techproducts/schema/managed"
+----
+
+The response body is a JSON document containing metadata about managed resources under the /schema root:
+
+[source,json]
+----
+{
+ "responseHeader":{
+ "status":0,
+ "QTime":3
+ },
+ "managedResources":[
+ {
+ "resourceId":"/schema/analysis/stopwords/english",
+ "class":"org.apache.solr.rest.schema.analysis.ManagedWordSetResource",
+ "numObservers":"1"
+ },
+ {
+ "resourceId":"/schema/analysis/synonyms/english",
+ "class":"org.apache.solr.rest.schema.analysis.ManagedSynonymGraphFilterFactory$SynonymManager",
+ "numObservers":"1"
+ }
+ ]
+}
+----
+
+You can also create new managed resource using PUT/POST to the appropriate URL – before ever configuring anything that uses these resources.
+
+For example, imagine we want to build up a set of German stop words.
+Before we can start adding stop words, we need to create the endpoint:
+
+`/solr/techproducts/schema/analysis/stopwords/german`
+
+To create this endpoint, send the following PUT/POST request to the endpoint we wish to create:
+
+[source,bash]
+----
+curl -X PUT -H 'Content-type:application/json' --data-binary \
+'{"class":"org.apache.solr.rest.schema.analysis.ManagedWordSetResource"}' \
+"http://localhost:8983/solr/techproducts/schema/analysis/stopwords/german"
+----
+
+Solr will respond with status code 200 if the request is successful.
+Effectively, this action registers a new endpoint for a managed resource in the RestManager.
+From here you can start adding German stop words as we saw above:
+
+[source,bash]
+----
+curl -X PUT -H 'Content-type:application/json' --data-binary '["die"]' \
+"http://localhost:8983/solr/techproducts/schema/analysis/stopwords/german"
+----
+
+For most users, creating resources in this way should never be necessary, since managed resources are created automatically when configured.
+
+However, You may want to explicitly delete managed resources if they are no longer being used by a Solr component.
+
+For instance, the managed resource for German that we created above can be deleted because there are no Solr components that are using it, whereas the managed resource for English stop words cannot be deleted because there is a token filter declared in the schema that is using it.
+
+[source,bash]
+----
+curl -X DELETE "http://localhost:8983/solr/techproducts/schema/analysis/stopwords/german"
+----
diff --git a/solr/solr-ref-guide/src/package-manager-internals.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager-internals.adoc
similarity index 100%
rename from solr/solr-ref-guide/src/package-manager-internals.adoc
rename to solr/solr-ref-guide/modules/configuration-guide/pages/package-manager-internals.adoc
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc
new file mode 100644
index 0000000..e07996e
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc
@@ -0,0 +1,210 @@
+= Package Management
+:page-children: package-manager-internals
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The package manager in Solr allows installation and updating of Solr-specific packages in Solr's cluster environment.
+
+In this system, a _package_ is a set of Java jar files (usually one) containing one or more xref:solr-plugins.adoc[].
+Each jar file is also accompanied by a signature string (which can be verified against a supplied public key).
+
+A key design aspect of this system is the ability to install or update packages in a cluster environment securely without the need to restart every node.
+
+Other elements of the design include the ability to install from a remote repository; package standardization; a command line interface (CLI); and a package store.
+
+This section will focus on how to use the package manager to install and update packages.
+For technical details, see the section xref:package-manager-internals.adoc[].
+
+== Interacting with the Package Manager
+
+The package manager (CLI) allows you to:
+
+* Add trusted repositories
+* List packages at a repository
+* Install desired packages
+* Deploy and undeploy packages to/from collections or cluster
+* Update packages when updates are available
+
+=== Enable the Package Manager
+
+The package manager is disabled by default.
+To enable it, start all Solr nodes with the `-Denable.packages=true` parameter.
+
+[source,bash]
+----
+$ bin/solr -c -Denable.packages=true
+----
+
+WARNING: There are security consequences to enabling the package manager.
+If an unauthorized user gained access to the system, they would have write access to ZooKeeper and could install packages from untrusted sources.
+Always ensure you have secured Solr with firewalls and xref:deployment-guide:authentication-and-authorization-plugins.adoc[] before enabling the package manager.
+
+=== Add Trusted Repositories
+
+A _repository_ is a location hosting one or many packages.
+Often, this is a web service that serves meta-information about packages, the package artifacts for downloading, and a public key to validate the jar file signatures while installing.
+
+In order to install packages into Solr, one has to add a repository hosting the packages.
+
+[source,bash]
+----
+$ bin/solr package add-repo <name-of-repo> <repo-url>
+----
+
+NOTE: Do not add repositories that you don't trust or control.
+Only add repositories that are based on HTTPS and avoid repositories based on HTTP to safeguard against MITM attacks.
+
+=== Listing and Installing Packages
+
+To list installed packages:
+
+[source,bash]
+----
+$ bin/solr package list-installed
+----
+
+To list packages available for installation from added repositories:
+
+[source,bash]
+----
+$ bin/solr package list-available
+----
+
+To install a package:
+
+[source,bash]
+----
+$ bin/solr package install <package-name>[:<version>]
+----
+
+=== Deploy a Package
+
+Once a package has been installed, the plugins contained in it can be used in a collection or at the cluster level.
+
+There are two ways to do this: either use the CLI's `deploy` command or manually.
+
+==== deploy Command
+
+If the package author states support for it, the package can be deployed with the CLI's `deploy` command:
+
+[source,bash]
+----
+$ bin/solr package deploy <package-name>:[version] -collections <collection1>[,<collection2>,...]
+----
+
+or
+
+[source,bash]
+----
+$ bin/solr package deploy <package-name>:[version] -cluster
+----
+
+The author may want you to confirm deployment of a package via a prompt.
+If you pass `-y` to the command, confirmation can be skipped.
+
+==== Manual Deploy
+
+It is also possible to deploy a package's collection level plugins manually by editing a xref:config-sets.adoc[configset] and reloading the collection.
+
+For example, if a package named `mypackage` contains a request handler, we would add it to a configset's `solrconfig.xml` like this:
+
+[source, xml]
+----
+<requestHandler name="/myhandler" class="mypackage:full.path.to.MyClass"></requestHandler>
+----
+
+Then use either the Collections API xref:deployment-guide:collection-management.adoc#reload[RELOAD command] or the xref:deployment-guide:collections-core-admin.adoc[Admin UI] to reload the collection.
+
+Next, set the package version that this collection is using.
+If the collection is named `collection1`, the package name is `mypackage`, and the installed version is `1.0.0`, the command would look like this:
+
+[source,bash]
+----
+curl "http://localhost:8983/api/collections/collection1/config/params" \
+ -H 'Content-type:application/json' -d "{set: {PKG_VERSIONS: {mypackage: '1.0.0'}}}"
+----
+
+For installing cluster level plugins manually, see https://issues.apache.org/jira/browse/SOLR-14404[cluster level request handlers].
+
+==== Verify the Deployment
+After deploying, verify that the collection is using the package:
+
+[source,bash]
+----
+$ bin/solr package list-deployed -c <collection>
+----
+
+=== Updating Packages
+
+In order to update a package, first step is make sure the updated version is available in the added repositories by running `list-available` command shown above in <<Listing and Installing Packages>>.
+
+Next, install the new version of the package from the repositories.
+
+[source,bash]
+----
+$ bin/solr package install <package-name>:<version>
+----
+
+Once you have installed the new version, you can selectively update each of your collections or the cluster level plugins.
+Assuming the old version is `1.0.0` of the package `mypackage`, and the new version is `2.0.0`, the command would be as follows:
+
+[source,bash]
+----
+$ bin/solr package deploy mypackage:2.0.0 --update -collections mycollection
+----
+or
+[source,bash]
+----
+$ bin/solr package deploy mypackage:2.0.0 --update -cluster
+----
+
+You can run the `list-deployed` command to verify that this collection is using the newly added version.
+
+=== Undeploy a Package
+
+If a package supports undeploying the plugins it contains (check package author's documentation), then a previously deployed package can be undeployed as follows:
+
+[source,bash]
+----
+$ bin/solr package undeploy <package-name> -collections <collection1>[,<collection2>,...]
+----
+
+=== Uninstall a Package
+
+If a package has been undeployed or was never deployed, then it can be uninstalled as follows:
+
+[source,bash]
+----
+$ bin/solr package uninstall <package-name>:<package-version>
+----
+
+or
+
+[source,bash]
+----
+$ bin/solr package deploy <package-name> -cluster
+----
+
+== Security
+
+The `add-repo` step should only be executed using HTTPS enabled repository urls only so as to prevent against MITM attacks when Solr is fetching the public key for the repository.
+This `add-repo` step registers the public key of the trusted repository, and hence can only be executed using the package manager (CLI) having direct write access to the trusted store of the package store (a special location in the package store that cannot be written to using the package store APIs).
+Also, it is critical to protect ZooKeeper from unauthorized write access.
+
+Also, keep in mind, that it is possible to install *any* package from a repository once it has been added.
+If you want to use some packages in production, a best practice is to setup your own repository and add that to Solr instead of adding a generic third-party repository that is beyond your administrative control.
+You might want to re-sign packages from a third-party repository using your own private keys and host them at your own repository.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/property-substitution.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/property-substitution.adoc
new file mode 100644
index 0000000..e70df74
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/property-substitution.adoc
@@ -0,0 +1,146 @@
+= Property Substitution in Configuration Files
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// *TODO* merge this page with core-discovery.adoc?
+
+Solr supports variable substitution of property values in configuration files, which allows runtime specification of various configuration options in `solrconfig.xml`.
+
+The syntax is `${propertyname[:option default value]`}.
+This allows defining a default that can be overridden when Solr is launched.
+If a default value is not specified, then the property _must_ be specified at runtime or the configuration file will generate an error when parsed.
+
+There are multiple methods for specifying properties that can be used in configuration files.
+Of those below, strongly consider "config overlay" as the preferred approach, as it stays local to the configset and is easy to modify.
+
+== JVM System Properties
+
+Any JVM system property, usually specified using the `-D` flag when starting the JVM, can be used as variables in any XML configuration file in Solr.
+
+For example, in the sample `solrconfig.xml` files, you will see this value which defines the locking type to use:
+
+[source,xml]
+----
+<lockType>${solr.lock.type:native}</lockType>
+----
+
+Which means the lock type defaults to "native" but when starting Solr you could override this using a JVM system property by launching Solr with:
+
+[source,bash]
+----
+bin/solr start -Dsolr.lock.type=none
+----
+
+In general, any Java system property that you want to set can be passed through the `bin/solr` script using the standard `-Dproperty=value` syntax.
+
+Alternatively, you can add common system properties to the `SOLR_OPTS` environment variable defined in the Solr include file (`bin/solr.in.sh` or `bin/solr.in.cmd`).
+For more information about how the Solr include file works, refer to: xref:deployment-guide:taking-solr-to-production.adoc[].
+
+== Config API to Override solrconfig.xml
+
+The xref:config-api.adoc[] allows you to use an API to modify Solr's configuration, specifically user defined properties.
+Changes made with this API are stored in a file named `configoverlay.json`.
+This file should only be edited with the API, but will look like this example:
+
+[source,json]
+----
+{
+ "userProps":{"update.autoCreateFields":"false"},
+ "requestHandler":{"/myterms":{
+ "name":"/myterms",
+ "class":"solr.SearchHandler",
+ "defaults":{
+ "terms":true,
+ "distrib":false},
+ "components":["terms"]}}}
+----
+
+For more details, see the section xref:config-api.adoc[].
+
+== User-Defined Properties in core.properties
+
+Every Solr core has a `core.properties` file, automatically created when using the APIs.
+When you create a SolrCloud collection, you can pass through custom parameters by prefixing the parameter name with `_property.name_` as a parameter.
+
+For example, to add a property named "my.custom.prop":
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1customprop]
+====
+[.tab-label]*V1 API*
+
+[source,bash]
+----
+http://localhost:8983/solr/admin/collections?action=CREATE&name=gettingstarted&numShards=1&property.my.custom.prop=edismax
+----
+====
+
+[example.tab-pane#v2]
+====
+[.tab-label]*V2 API*
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{"create": {"name": "gettingstarted", "numShards": "1", "property.my.custom.prop": "edismax"}}' http://localhost:8983/api/collections
+----
+====
+--
+
+This will create a `core.properties` file that has at least the following properties (others omitted for brevity):
+
+[source,properties]
+----
+#core.properties
+name=gettingstarted
+my.custom.prop=edismax
+----
+
+The `my.custom.prop` property can then be used as a variable, such as in `solrconfig.xml`:
+
+[source,xml]
+----
+<requestHandler name="/select">
+ <lst name="defaults">
+ <str name="defType">${my.custom.prop}</str>
+ </lst>
+</requestHandler>
+----
+
+== Implicit Core Properties
+
+Several attributes of a Solr core are available as "implicit" properties that can be used in variable substitution, independent of where or how the underlying value is initialized.
+
+For example, regardless of whether the name for a particular Solr core is explicitly configured in `core.properties` or inferred from the name of the instance directory, the implicit property `solr.core.name` is available for use as a variable in that core's configuration file:
+
+[source,xml]
+----
+<requestHandler name="/select">
+ <lst name="defaults">
+ <str name="collection_name">${solr.core.name}</str>
+ </lst>
+</requestHandler>
+----
+
+All implicit properties use the `solr.core.` name prefix, and reflect the runtime value of the equivalent xref:core-discovery.adoc[`core.properties` property]:
+
+* `solr.core.name`
+* `solr.core.config`
+* `solr.core.schema`
+* `solr.core.dataDir`
+* `solr.core.transient`
+* `solr.core.loadOnStartup`
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/realtime-get.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/realtime-get.adoc
new file mode 100644
index 0000000..e794bce
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/realtime-get.adoc
@@ -0,0 +1,222 @@
+= RealTime Get
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+For index updates to be visible (searchable), some kind of commit must reopen a searcher to a new point-in-time view of the index.
+
+The *realtime get* feature allows retrieval (by `unique-key`) of the latest version of any documents without the associated cost of reopening a searcher.
+This is primarily useful when using Solr as a NoSQL data store and not just a search index.
+
+Real Time Get relies on the update log feature, which is enabled by default and can be configured in `solrconfig.xml`:
+
+[source,xml]
+----
+<updateLog>
+ <str name="dir">${solr.ulog.dir:}</str>
+</updateLog>
+----
+
+Real Time Get requests can be performed using the `/get` handler which exists implicitly in Solr - see xref:implicit-requesthandlers.adoc[] - it's equivalent to the following configuration:
+
+[source,xml]
+----
+<requestHandler name="/get" class="solr.RealTimeGetHandler">
+ <lst name="defaults">
+ <str name="omitHeader">true</str>
+ </lst>
+</requestHandler>
+----
+
+For example, if you started Solr using the `bin/solr -e techproducts` example command, you could then index a new document without committing it, like so:
+
+[source,bash]
+----
+curl 'http://localhost:8983/solr/techproducts/update/json?commitWithin=10000000' \
+ -H 'Content-type:application/json' -d '[{"id":"mydoc","name":"realtime-get test!"}]'
+----
+
+If you search for this document, it should not be found yet:
+
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/query?q=id:mydoc
+----
+
+[source,json]
+----
+{"response":
+ {"numFound":0,"start":0,"docs":[]}
+}
+----
+
+However if you use the Real Time Get handler exposed at `/get`, you can retrieve the document:
+
+[.dynamic-tabs]
+--
+[.tab-pane#v1get]
+====
+[.tab-label]*V1 API*
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/get?id=mydoc
+----
+
+[source,json]
+----
+{"doc": {
+ "id": "mydoc",
+ "name": "realtime-get test!",
+ "_version_": 1487137811571146752
+ }
+}
+----
+====
+
+[.tab-pane#v2get]
+====
+[.tab-label]*V2 API*
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/get?id=mydoc
+----
+
+[source,json]
+----
+{"doc": {
+ "id": "mydoc",
+ "name": "realtime-get test!",
+ "_version_": 1487137811571146752
+ }
+}
+----
+====
+--
+
+You can also specify multiple documents at once via the `ids` parameter and a comma separated list of ids, or by using multiple `id` parameters.
+If you specify multiple ids, or use the `ids` parameter, the response will mimic a normal query response to make it easier for existing clients to parse.
+
+For example:
+
+[.dynamic-tabs]
+--
+[.tab-pane#v1getids]
+====
+[.tab-label]*V1 API*
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/get?ids=mydoc,IW-02
+http://localhost:8983/solr/techproducts/get?id=mydoc&id=IW-02
+----
+
+[source,json]
+----
+{"response":
+ {"numFound":2,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752},
+ {
+ "id":"IW-02",
+ "name":"iPod & iPod Mini USB 2.0 Cable"
+ }
+ ]
+ }
+}
+----
+====
+
+[.tab-pane#v2getids]
+====
+[.tab-label]*V2 API*
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/get?ids=mydoc,IW-02
+http://localhost:8983/api/collections/techproducts/get?id=mydoc&id=IW-02
+----
+
+[source,json]
+----
+{"response":
+ {"numFound":2,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752},
+ {
+ "id":"IW-02",
+ "name":"iPod & iPod Mini USB 2.0 Cable"
+ }
+ ]
+ }
+}
+----
+====
+--
+
+Real Time Get requests can also be combined with filter queries, specified with an xref:query-guide:common-query-parameters.adoc#fq-filter-query-parameter[`fq` parameter]:
+
+[.dynamic-tabs]
+--
+[.tab-pane#v1getfq]
+====
+[.tab-label]*V1 API*
+[source,bash]
+----
+http://localhost:8983/solr/techproducts/get?id=mydoc&id=IW-02&fq=name:realtime-get
+----
+
+[source,json]
+----
+{"response":
+ {"numFound":1,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752}
+ ]
+ }
+}
+----
+====
+
+[.tab-pane#v2getfq]
+====
+[.tab-label]*V2 API*
+[source,bash]
+----
+http://localhost:8983/api/collections/techproducts/get?id=mydoc&id=IW-02&fq=name:realtime-get
+----
+
+[source,json]
+----
+{"response":
+ {"numFound":1,"start":0,"docs":
+ [ { "id":"mydoc",
+ "name":"realtime-get test!",
+ "_version_":1487137811571146752}
+ ]
+ }
+}
+----
+====
+--
+
+[WARNING]
+====
+Do *NOT* disable the realtime get handler at `/get` if you are using SolrCloud.
+Doing so will result in any leader election to cause a full sync in *ALL* replicas for the shard in question.
+
+Similarly, a replica recovery will also always fetch the complete index from the leader because a partial sync will not be possible in the absence of this handler.
+====
diff --git a/solr/solr-ref-guide/src/replica-placement-plugins.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/replica-placement-plugins.adoc
similarity index 100%
rename from solr/solr-ref-guide/src/replica-placement-plugins.adoc
rename to solr/solr-ref-guide/modules/configuration-guide/pages/replica-placement-plugins.adoc
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/request-parameters-api.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/request-parameters-api.adoc
new file mode 100644
index 0000000..11b5e51
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/request-parameters-api.adoc
@@ -0,0 +1,230 @@
+= Request Parameters API
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Request Parameters API allows creating parameter sets, a.k.a. paramsets, that can override or take the place of parameters defined in `solrconfig.xml`.
+
+The parameter sets defined with this API can be used in requests to Solr, or referenced directly in `solrconfig.xml` request handler definitions.
+
+It is really another endpoint of the xref:config-api.adoc[] instead of a separate API, and has distinct commands.
+It does not replace or modify any sections of `solrconfig.xml`, but instead provides another approach to handling parameters used in requests.
+It behaves in the same way as the Config API, by storing parameters in another file that will be used at runtime.
+In this case, the parameters are stored in a file named `params.json`.
+This file is kept in ZooKeeper when running SolrCloud or in the `conf` directory of a user-managed cluster or single-node installation.
+
+The settings stored in `params.json` are used at query time to override settings defined in `solrconfig.xml` in some cases as described below.
+
+When might you want to use this feature?
+
+* To avoid frequently editing your `solrconfig.xml` to update request parameters that change often.
+* To reuse parameters across various request handlers.
+* To mix and match parameter sets at request time.
+* To avoid a reload of your collection for small parameter changes.
+
+== The Request Parameters Endpoint
+
+All requests are sent to the `/config/params` endpoint of the Config API.
+
+== Configuring Request Parameters
+
+The request to set, or update request parameters is sent as a set of maps with names.
+These objects can be directly used in a request or a request handler definition.
+The request to delete parameter set is sent as list of names or a name.
+
+The available commands are:
+
+* `set`: Create or overwrite a parameter set map.
+* `delete`: Remove a request parameter set map.
+* `update`: update a parameter set map.
+This is equivalent to a `map.putAll(newMap)`.
+Both maps are merged and if the new map has same keys as the old they are overwritten.
+
+You can mix these commands into a single request if necessary.
+
+For `set` or `update` commands, each map must include a name so it can be referenced later, either in a direct request to Solr or in a request handler definition.
+
+In the following example, we are setting 2 sets of parameters named 'myFacets' and 'myQueries'.
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "set":{
+ "myFacets":{
+ "facet":"true",
+ "facet.limit":5}},
+ "set":{
+ "myQueries":{
+ "defType":"edismax",
+ "rows":"5",
+ "df":"text_all"}}
+}'
+----
+
+In the above example all the parameters are equivalent to the "defaults" in `solrconfig.xml`.
+It is possible to add invariants and appends as follows:
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "set":{
+ "my_handler_params":{
+ "facet.limit":5,
+ "_invariants_": {
+ "facet":true,
+ },
+ "_appends_":{"facet.field":["field1","field2"]
+ }
+ }}
+}'
+----
+
+In the following example, two set of parameters named 'myFacets' and 'myQueries' are deleted.
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "delete":[
+ "myFacets",
+ "myQueries"
+ ]
+}'
+----
+
+When deleting a single parameter set, the value could be specified as string instead of list.
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json' -d '{
+ "delete":"myFacets"
+}'
+----
+
+== Using Request Parameters with RequestHandlers
+
+After creating the `my_handler_params` paramset in the above section, it is possible to define a request handler as follows:
+
+[source,xml]
+----
+<requestHandler name="/my_handler" class="solr.SearchHandler" useParams="my_handler_params"/>
+----
+
+It will be equivalent to a standard request handler definition like:
+
+[source,xml]
+----
+<requestHandler name="/my_handler" class="solr.SearchHandler">
+ <lst name="defaults">
+ <int name="facet.limit">5</int>
+ </lst>
+ <lst name="invariants">
+ <bool name="facet">true</bool>
+ </lst>
+ <lst name="appends">
+ <arr name="facet.field">
+ <str>field1</str>
+ <str>field2</str>
+ </arr>
+ </lst>
+</requestHandler>
+----
+
+=== Implicit RequestHandlers with the Request Parameters API
+
+Solr ships with many out-of-the-box request handlers that may only be configured via the Request Parameters API, because their configuration is not present in `solrconfig.xml`.
+See xref:implicit-requesthandlers.adoc[] for the paramset to use when configuring an implicit request handler.
+
+=== Viewing Expanded Paramsets and Effective Parameters with RequestHandlers
+
+To see the expanded paramset and the resulting effective parameters for a RequestHandler defined with `useParams`, use the `expandParams` request parameter.
+As an example, for the `/export` request handler:
+
+[source,bash]
+----
+$ curl http://localhost:8983/solr/techproducts/config/requestHandler?componentName=/export&expandParams=true
+----
+
+== Viewing Request Parameters
+
+To see the paramsets that have been created, you can use the `/config/params` endpoint to read the contents of `params.json`, or use the name in the request:
+
+[source,bash]
+----
+$ curl http://localhost:8983/solr/techproducts/config/params
+
+#Or use the paramset name
+$ curl http://localhost:8983/solr/techproducts/config/params/myQueries
+----
+
+== The useParams Parameter
+
+When making a request, the `useParams` parameter applies the request parameters sent to the request.
+This is translated at request time to the actual parameters.
+
+For example (using the names we set up in the earlier examples, please replace with your own name):
+
+[source,text]
+----
+http://localhost/solr/techproducts/select?useParams=myQueries
+----
+
+It is possible to pass more than one parameter set in the same request.
+For example:
+
+[source,text]
+----
+http://localhost/solr/techproducts/select?useParams=myFacets,myQueries
+----
+
+In the above example the parameter set 'myQueries' is applied on top of 'myFacets'.
+So, values in 'myQueries' take precedence over values in 'myFacets'.
+Additionally, any values passed in the request take precedence over `useParams` parameters.
+This acts like the "defaults" specified in the `<requestHandler>` definition in `solrconfig.xml`.
+
+The parameter sets can be used directly in a request handler definition as follows.
+Please note that the `useParams` specified is always applied even if the request contains `useParams`.
+
+[source,xml]
+----
+<requestHandler name="/terms" class="solr.SearchHandler" useParams="myQueries">
+ <lst name="defaults">
+ <bool name="terms">true</bool>
+ <bool name="distrib">false</bool>
+ </lst>
+ <arr name="components">
+ <str>terms</str>
+ </arr>
+</requestHandler>
+----
+
+To summarize, parameters are applied in this order:
+
+* parameters defined in `<invariants>` in `solrconfig.xml`.
+* parameters applied in `invariants` in `params.json` and are specified in the request handler definition or even in a single request.
+* parameters defined in the request directly.
+* parameter sets defined in the request, in the order they have been listed with `useParams`.
+* parameter sets defined in `params.json` that have been defined in the request handler.
+* parameters defined in `<defaults>` in `solrconfig.xml`.
+
+== Public APIs
+
+The RequestParams Object can be accessed using the method `SolrConfig#getRequestParams()`.
+Each paramset can be accessed by their name using the method `RequestParams#getRequestParams(String name)`.
+
+== Examples Using the Request Parameters API
+
+The Solr "films" example demonstrates the use of the parameters API.
+You can use this example in your Solr installation (in the `example/films` directory) or view the files in the Solr GitHub mirror at https://github.com/apache/solr/tree/main/solr/example/films.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/requestdispatcher.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/requestdispatcher.adoc
new file mode 100644
index 0000000..d706d58
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/requestdispatcher.adoc
@@ -0,0 +1,212 @@
+= RequestDispatcher
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The `requestDispatcher` element of `solrconfig.xml` controls the way the Solr HTTP `RequestDispatcher` implementation responds to requests.
+
+Included are parameters for defining if it should handle `/select` urls (for Solr 1.1 compatibility), if it will support remote streaming, the maximum size of file uploads and how it will respond to HTTP cache headers in requests.
+
+== handleSelect Element
+
+[IMPORTANT]
+====
+`handleSelect` is for legacy back-compatibility; those new to Solr do not need to change anything about the way this is configured by default.
+====
+
+The first configurable item is the `handleSelect` attribute on the `<requestDispatcher>` element itself.
+This attribute can be set to one of two values, either "true" or "false".
+It governs how Solr responds to requests such as `/select?qt=XXX`.
+The default value "false" will ignore requests to `/select` if a request handler is not explicitly registered with the name `/select`.
+A value of "true" will route query requests to the parser defined with the `qt` value if a request handler is not explicitly registered with the name `/select`.
+
+In recent versions of Solr, a `/select` request handler is defined by default, so a value of "false" will work fine.
+See the section xref:requesthandlers-searchcomponents.adoc[] for more information.
+
+[source,xml]
+----
+<requestDispatcher handleSelect="true" >
+ ...
+</requestDispatcher>
+----
+
+== requestParsers Element
+
+The `<requestParsers>` sub-element controls values related to parsing requests.
+This is an empty XML element that doesn't have any content, only attributes.
+
+`enableRemoteStreaming`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+Controls whether remote streaming of content is allowed.
+When set to `false`, streaming will not be allowed.
+Setting it to `true` lets you specify the location of content to be streamed using `stream.file` or `stream.url` parameters.
+
+`enableStreamBody`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
++
+This attribute controls whether streaming content from the HTTP parameter `stream.body` is allowed.
+When set to `false`, streaming will not be allowed.
+Setting it to `true` lets you pass data in the `stream.body` parameter.
++
+If you enable remote streaming, be sure that you have authentication enabled.
+Otherwise, someone could potentially gain access to your content by accessing arbitrary URLs.
+It's also a good idea to place Solr behind a firewall to prevent it from being accessed from untrusted clients.
+
+`multipartUploadLimitInKB`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `-1`
+|===
++
+This attribute sets an upper limit in kilobytes on the size of a document that may be submitted in a multi-part HTTP POST request.
+The value specified is multiplied by 1024 to determine the size in bytes.
+A value of `-1` means MAX_INT, which is also the system default if omitted.
+
+`formdataUploadLimitInKB`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `-1`
+|===
++
+This attribute sets a limit in kilobytes on the size of form data (`application/x-www-form-urlencoded`) submitted in a HTTP POST request, which can be used to pass request parameters that will not fit in a URL.
+A value of `-1` means MAX_INT, which is also the system default if omitted.
+
+`addHttpRequestToContext`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+This attribute can be used to indicate that the original `HttpServletRequest` object should be included in the context map of the `SolrQueryRequest` using the key `httpRequest`.
+This `HttpServletRequest` is not used by any Solr component, but may be useful when developing custom plugins.
+
+[source,xml]
+----
+<requestParsers enableRemoteStreaming="false"
+ enableStreamBody="false"
+ multipartUploadLimitInKB="2048"
+ formdataUploadLimitInKB="2048"
+ addHttpRequestToContext="false" />
+----
+
+The below command is an example of how to enable RemoteStreaming and BodyStreaming through the xref:config-api.adoc#commands-for-common-properties[Config API]:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#v1enablestreaming]
+====
+[.tab-label]*V1 API*
+[source,bash]
+----
+curl -H 'Content-type:application/json' -d '{"set-property": {"requestDispatcher.requestParsers.enableRemoteStreaming": true}, "set-property": {"requestDispatcher.requestParsers.enableStreamBody": true}}' http://localhost:8983/solr/gettingstarted/config
+----
+====
+
+[example.tab-pane#v2enablestreaming]
+====
+[.tab-label]*V2 API User-Managed / Single-Node*
+[source,bash]
+----
+curl -H 'Content-type:application/json' -d '{"set-property": {"requestDispatcher.requestParsers.enableRemoteStreaming": true}, "set-property":{"requestDispatcher.requestParsers.enableStreamBody": true}}' http://localhost:8983/api/cores/gettingstarted/config
+----
+====
+
+[example.tab-pane#v2enablestreamingcloud]
+====
+[.tab-label]*V2 API SolrCloud*
+[source,bash]
+----
+curl -H 'Content-type:application/json' -d '{"set-property": {"requestDispatcher.requestParsers.enableRemoteStreaming": true}, "set-property":{"requestDispatcher.requestParsers.enableStreamBody": true}}' http://localhost:8983/api/collections/gettingstarted/config
+----
+====
+--
+
+== httpCaching Element
+
+The `<httpCaching>` element controls HTTP cache control headers.
+Do not confuse these settings with Solr's internal cache configuration.
+This element controls caching of HTTP responses as defined by the W3C HTTP specifications.
+
+This element allows for three attributes and one sub-element.
+The attributes of the `<httpCaching>` element control whether a 304 response to a GET request is allowed, and if so, what sort of response it should be.
+When an HTTP client application issues a GET, it may optionally specify that a 304 response is acceptable if the resource has not been modified since the last time it was fetched.
+
+`never304`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+If present with the value `true`, then a GET request will never respond with a 304 code, even if the requested resource has not been modified.
+When this attribute is set to `true`, the next two attributes are ignored.
+Setting this to `true` is handy for development, as the 304 response can be confusing when tinkering with Solr responses through a web browser or other client that supports cache headers.
+
+`lastModFrom`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `openTime`
+|===
++
+This attribute may be set to either `openTime` or `dirLastMod`.
++
+The value `openTime` indicates that last modification times, as compared to the If-Modified-Since header sent by the client, should be calculated relative to the time the Searcher started.
++
+Use `dirLastMod` if you want times to exactly correspond to when the index was last updated on disk.
+
+`etagSeed`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+This value of this attribute is sent as the value of the `ETag` header.
+Changing this value can be helpful to force clients to re-fetch content even when the indexes have not changed; for example, when you've made some changes to the configuration.
+
+[source,xml]
+----
+<httpCaching never304="false"
+ lastModFrom="openTime"
+ etagSeed="Solr">
+ <cacheControl>max-age=30, public</cacheControl>
+</httpCaching>
+----
+
+=== cacheControl Element
+
+In addition to these attributes, `<httpCaching>` accepts one child element: `<cacheControl>`.
+The content of this element will be sent as the value of the Cache-Control header on HTTP responses.
+This header is used to modify the default caching behavior of the requesting client.
+The possible values for the Cache-Control header are defined by the HTTP 1.1 specification in http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9[Section 14.9].
+
+Setting the max-age field controls how long a client may re-use a cached response before requesting it again from the server.
+This time interval should be set according to how often you update your index and whether or not it is acceptable for your application to use content that is somewhat out of date.
+Setting `must-revalidate` will tell the client to validate with the server that its cached copy is still good before re-using it.
+This will ensure that the most timely result is used, while avoiding a second fetch of the content if it isn't needed, at the cost of a request to the server to do the check.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/requesthandlers-searchcomponents.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/requesthandlers-searchcomponents.adoc
new file mode 100644
index 0000000..8a3144c
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/requesthandlers-searchcomponents.adoc
@@ -0,0 +1,330 @@
+= Request Handlers and Search Components
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+After the `<query>` section of `solrconfig.xml`, request handlers and search components are configured.
+
+A _request handler_ processes requests coming to Solr.
+These might be query requests, index update requests or specialized interactions such as xref:deployment-guide:ping.adoc[].
+
+Not all handlers are defined explicitly in `solrconfig.xml`, many are defined implicitly.
+See xref:implicit-requesthandlers.adoc[] for details.
+
+Additionally, handlers can be defined or overridden in `configoverlay.json` by using xref:config-api.adoc[].
+Finally, independent parameter sets can be also defined by xref:request-parameters-api.adoc[].
+They will be stored in `params.json` file and referenced with <<paramsets-and-useparams,useParams>>.
+
+All of this multi-layered configuration can be verified via xref:config-api.adoc[].
+
+Defining your own config handlers is often a useful way to provide defaults and advanced configuration to support business cases and simplify client API.
+At the same time, using every single option explained in this guide, will most certainly cause some confusion about which parameter is actually used when.
+
+== Defining and Calling Request Handlers
+
+Every request handler is defined with a name and a class.
+The name of the request handler is referenced with the request to Solr, typically as a path.
+For example, if Solr is installed at `\http://localhost:8983/solr/`, and you have a collection named "gettingstarted", you can make a request that looks like this:
+
+[source,text]
+----
+http://localhost:8983/solr/gettingstarted/select?q=solr
+----
+
+This query will be processed by the request handler with the name `/select`.
+We've only used the "q" parameter here, which includes our query term, a simple keyword of "solr".
+If the request handler has more default parameters defined, those will be used with any query we send to that request handler unless they are overridden by the client (or user) in the query itself.
+
+If you have another request handler defined, you could send your request with that name.
+For example, `/update` is an implicit request handler that handles index updates (i.e., sending new documents to the index).
+By default, `/select` is a request handler that handles query requests and one expected by most examples and tools.
+
+Request handlers can also process requests for nested paths in their names,
+for example, a request using `/myhandler/extrapath` may be processed by a request handler registered with the name `/myhandler`.
+If a request handler is explicitly defined by the name `/myhandler/extrapath`, that would take precedence over the nested path.
+This assumes you are using the request handler classes included with Solr; if you create your own request handler,
+you should make sure it includes the ability to handle nested paths if you want to use them with your custom request handler.
+
+If a request handler is not expected to be used very often, it can be marked with `startup="lazy"` to avoid loading until needed.
+
+[source,xml]
+----
+<requestHandler name="/spell" class="solr.SearchHandler" startup="lazy">
+ ...
+</requestHandler>
+----
+
+== Configuring Request Handlers
+There are 3 ways to configure request handlers inside their definitions and another 3 ways to configure them somewhere else.
+
+=== Request Parameters (GET and POST)
+The easiest and most flexible way is to provide parameters with standard GET or POST requests.
+
+Here is an example of sending parameters `id`, `fl`, and `wt` to `/select` Search Handler.
+Notice the URL-encoded space (as +) for the values of `fl` parameter.
+
+[source,text]
+----
+http://localhost:8983/solr/techproducts/select?q=id:SP2514N&fl=id+name&wt=xml
+----
+
+The following is an example of parameters being sent through the POST form to `/query` Search Handler using the xref:query-guide:json-request-api.adoc[].
+
+[source,bash]
+----
+curl http://localhost:8983/solr/techproducts/query -d '
+{
+ "query" : "memory",
+ "filter" : "inStock:true"
+}'
+----
+
+Either way, the parameters are extracted and combined with other options explained below.
+
+=== Defaults, Appends, and Invariants
+
+==== Defaults
+
+The most common way to configure request handlers is by providing `defaults` section.
+The parameters there are used unless they are overridden by any other method.
+
+[source,xml]
+----
+<requestHandler name="/select" class="solr.SearchHandler">
+ <lst name="defaults">
+ <str name="echoParams">explicit</str>
+ <int name="rows">10</int>
+ </lst>
+</requestHandler>
+----
+
+This example defined a useful troubleshooting parameter xref:query-guide:common-query-parameters.adoc#echoparams-parameter[echoParams], with value that returns only params defined in the request itself (no defaults), set it to `all` for more information.
+It also defines the `rows` parameter, with how many results to return (per page) (10 is a true default actually, so this is a redundant definition, if you are not going to modify it).
+
+Note also that the way the defaults are defined in the list varies if the parameter is a string, an integer, or another type.
+
+Here is how some other primitive types are represented:
+
+[source,xml]
+----
+ <lst name="defaults">
+ <float name="hl.regex.slop">0.5</float>
+ <bool name="default">true</bool>
+ </lst>
+----
+
+Other specialized types may exist, they would be explained in the sections for relevant components.
+
+==== Appends
+
+In the `appends` section, you can define parameters that are added those already defined elsewhere.
+These are useful when the same parameter may be meaningfully defined multiple times, such as for xref:query-guide:common-query-parameters.adoc#fq-filter-query-parameter[filter queries].
+There is no mechanism in Solr to allow a client to override these additions, so you should be absolutely sure you always want these parameters applied to queries.
+
+[source,xml]
+----
+<lst name="appends">
+ <str name="fq">inStock:true</str>
+</lst>
+----
+
+In this example, the filter query `inStock:true` will always be added to every query, enforcing that only available "products" are returned.
+
+==== Invariants
+
+In the `invariants` section, you can define parameters that cannot be overridden by a client.
+The values defined in the `invariants` section will always be used regardless of the values specified by the user, by the client, in `defaults` or in `appends`.
+
+
+[source,xml]
+----
+<lst name="invariants">
+ <str name="facet.field">cat</str>
+ <str name="facet.field">manu_exact</str>
+ <str name="facet.query">price:[* TO 500]</str>
+ <str name="facet.query">price:[500 TO *]</str>
+</lst>
+----
+
+In this example, the `facet.field` and `facet.query` params would be fixed, limiting the facets clients can use.
+Faceting is not turned on by default - but if the client does specify `facet=true` in the request,
+these are the only facets they will be able to see counts for; regardless of what other `facet.field` or `facet.query` params they may specify.
+
+=== InitParams
+It is also possible to configure defaults for request handlers with a section called `initParams`.
+These defaults can be used when you want to have common properties that will be used by each separate handler.
+For example, if you intend to create several request handlers that will all request the same list of fields in the response, you can configure an `initParams` section with your list of fields.
+For more information about `initParams`, see the section xref:initparams.adoc[].
+
+=== Paramsets and UseParams
+If you are expecting to change the parameters often, or if you want define sets of parameters that you can apply on the fly,
+you can define them with xref:request-parameters-api.adoc[] and then invoke them
+by providing one or more in `useParams` setting either in the handler definition itself or as a query parameter.
+
+[source,xml]
+----
+<requestHandler name="/terms" class="solr.SearchHandler" useParams="myQueries">
+
+...
+</requestHandler>
+----
+
+[source,text]
+----
+http://localhost/solr/techproducts/select?useParams=myFacets,myQueries
+----
+
+If a paramset is called but is not defined, it is ignored.
+This allows most xref:implicit-requesthandlers.adoc[] to call specific paramsets that you can define later, as needed.
+
+
+== Search Handlers
+
+Search Handlers are very important to Solr, as the data is indexed (roughly) once but is searched many times.
+The whole design of Solr (and Lucene) is optimising data for searching and Search Handler is a flexible gateway to that.
+
+The following sections are allowed within a Search Handler:
+
+[source,xml]
+----
+<requestHandler name="/select" class="solr.SearchHandler">
+... defaults/appends/invariants
+... first-components/last-components or components
+... shardHandlerFactory
+</requestHandler>
+----
+
+All the blocks are optional, especially since parameters can also be provided with `initParams` and `useParams`.
+
+The defaults/appends/invariants blocks were described earlier in <<defaults-appends-and-invariants>>.
+All query parameters can be defined as parameters for any of the Search Handlers.
+
+The Search Components blocks are described next, and xref:deployment-guide:solrcloud-distributed-requests.adoc#configuring-the-shardhandlerfactory[shardHandlerFactory] is for fine-tuning of the SolrCloud distributed requests.
+
+=== Defining Search Components
+The search components themselves are defined outside of the Request Handlers and then are referenced from various Search Handlers that want to use them.
+Most Search Handlers use the default - implicit - stack of Search Components and only sometimes need to augment them with additional components prepended or appended.
+It is quite rare - and somewhat brittle - to completely override the component stack, though it is used in examples to clearly demonstrate the effect of a specific Search Component.
+
+==== Default Components
+
+As you can see below, what we see as a search experience is mostly a sequence of components defined below.
+They are called in the order listed.
+
+[cols="20,40,40",options="header"]
+|===
+|Component Name |Class Name |More Information
+|query |`solr.QueryComponent` |Described in the section xref:query-guide:query-syntax-and-parsers.adoc[].
+|facet |`solr.FacetComponent` |Original parameter-based facet component, described in the section xref:query-guide:faceting.adoc[].
+|facet_module |`solr.facet.FacetModule` | JSON Faceting and Analytics module, described in the section xref:query-guide:json-facet-api.adoc[].
+|mlt |`solr.MoreLikeThisComponent` |Described in the section xref:query-guide:morelikethis.adoc[].
+|highlight |`solr.HighlightComponent` |Described in the section xref:query-guide:highlighting.adoc[].
+|stats |`solr.StatsComponent` |Described in the section xref:query-guide:stats-component.adoc[].
+|expand |`solr.ExpandComponent` |Described in the section xref:query-guide:collapse-and-expand-results.adoc[].
+|terms |`solr.TermsComponent` |Described in the section xref:query-guide:terms-component.adoc[].
+|debug |`solr.DebugComponent` |Described in the section on xref:query-guide:common-query-parameters.adoc#debug-parameter[debug Parameter].
+|===
+
+==== Shipped Custom Components
+Apart from default components, Solr ships with a number of additional - very useful - components.
+They do need to defined and referenced in `solrconfig.xml` to be actually used.
+
+* `AnalyticsComponent`, described in the section xref:query-guide:analytics.adoc[].
+* `ClusteringComponent`, described in the section xref:query-guide:result-clustering.adoc[].
+* `PhrasesIdentificationComponent`, used to identify & score "phrases" found in the input string, based on shingles in indexed fields, described in the {solr-javadocs}/core/org/apache/solr/handler/component/PhrasesIdentificationComponent.html[PhrasesIdentificationComponent] javadocs.
+* `QueryElevationComponent`, described in the section xref:query-guide:query-elevation-component.adoc[].
+* `RealTimeGetComponent`, described in the section xref:realtime-get.adoc[].
+* `ResponseLogComponent`, used to record which documents are returned to the user via the Solr log, described in the {solr-javadocs}/core/org/apache/solr/handler/component/ResponseLogComponent.html[ResponseLogComponent] javadocs.
+* `SpellCheckComponent`, described in the section xref:query-guide:spell-checking.adoc[].
+* `SuggestComponent`, described in the section xref:query-guide:suggester.adoc[].
+* `TermVectorComponent`, described in the section xref:query-guide:term-vector-component.adoc[].
+
+Some third party components are also linked from https://solr.cool/ website.
+
+==== Defining Custom Search Components
+To define custom component, the syntax is:
+
+[source,xml]
+----
+<searchComponent name="spellcheck" class="solr.SpellCheckComponent">
+ <lst name="spellchecker">
+ <str name="classname">solr.IndexBasedSpellChecker</str>
+ ...
+ </lst>
+</searchComponent>
+----
+
+Custom components often have configuration elements not described here.
+Check specific component's documentation/examples for details.
+
+Notice: If you register a new search component with one of the default names, the newly defined component will be used instead of the default.
+This allows to override a specific component, while not having to worry so much about upgrading Solr.
+
+=== Referencing Search Components
+
+It's possible to define some components as being used before (with `first-components`) or after (with `last-components`) the default components listed above.
+
+[source,xml]
+----
+<searchComponent name="..." class="...">
+ <arr name="first-components">
+ <str>mycomponent</str>
+ </arr>
+ <arr name="last-components">
+ <str>spellcheck</str>
+ </arr>
+</searchComponent>
+----
+
+NOTE: The component registered with the name "debug" will always be executed after the "last-components"
+
+If you define `components` instead, the <<default-components>> will not be executed, and `first-components` and `last-components` are disallowed.
+This should be considered as a last-resort option as the default list may change in a later Solr version.
+
+[source,xml]
+----
+<searchComponent name="..." class="...">
+ <arr name="components">
+ <str>mycomponent</str>
+ <str>query</str>
+ <str>debug</str>
+ </arr>
+</searchComponent>
+----
+
+
+== Update Request Handlers
+
+The Update Request Handlers are request handlers which process updates to the index.
+Most of the available update request handlers are xref:implicit-requesthandlers.adoc#update-handlers[implicit] and can be customized by defining properly named Paramsets.
+
+If you need to define additional Update Request Handler, the syntax is:
+
+[source,xml]
+----
+<requestHandler name="/update/json" class="solr.UpdateRequestHandler">
+... defaults/appends/invariants
+</requestHandler>
+
+----
+
+The full details are covered in the section xref:indexing-guide:indexing-with-update-handlers.adoc[].
+
+Similar to Search Components for Search Handlers, Solr has document-preprocessing plugins for Update Request Handlers,
+called xref:update-request-processors.adoc[],
+which also allow for default and custom configuration chains.
+
+Note: Do not confuse Update Request Handlers with xref:commits-transaction-logs.adoc[`updateHandler`] section also defined in `solrconfig.xml`.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/resource-loading.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/resource-loading.adoc
new file mode 100644
index 0000000..bcdbe17
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/resource-loading.adoc
@@ -0,0 +1,46 @@
+= Resource Loading
+
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Solr components can be configured using *resources*: data stored in external files that may be referred to in a location-independent fashion.
+
+Examples of resources include: files needed by schema components, e.g., a stopword list for xref:indexing-guide:filters.adoc#stop-filter[Stop Filter]; and machine-learned models for xref:query-guide:learning-to-rank.adoc[].
+_Resources are typically resolved from the configSet_ but there are other options too.
+
+Solr's resources are generally only loaded initially when the Solr collection or Solr core is loaded.
+After you update a resource, you'll typically need to _reload_ the affected collections when running SolrCloud, or the cores when running a user-managed cluster or single-node installation.
+Restarting all affected Solr nodes also works.
+xref:managed-resources.adoc[] can be manipulated via APIs and do not need an explicit reload.
+
+== Resources in Configsets
+
+xref:config-sets.adoc[] are the directories containing `solrconfig.xml`, the schema, and resources referenced by them.
+In SolrCloud they are stored in ZooKeeper.
+In a user-managed cluster and a single-node installation they are stored on the file system.
+In any mode, resources may be shared or may be dedicated to a configSet.
+Prefer to put resources here.
+
+== Resources in Other Places
+
+Resources can also be placed in an arbitrary directory and xref:libs.adoc#lib-directives-in-solrconfig[referenced] from a `<lib />` directive in `solrconfig.xml`, provided the directive refers to a directory and not the actual resource file.
+Example: `<lib path="/volume/models/" />`
+This choice may make sense if the resource is too large for a configset in ZooKeeper.
+However it's up to you to somehow ensure that all nodes in your cluster have access to these resources.
+
+Finally, and this is very unusual, resources can also be packaged inside `.jar` files from which they will be referenced.
+That might make sense for default resources wherein a plugin user can override it via placing the same-named file in a configSet.
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/schema-factory.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/schema-factory.adoc
new file mode 100644
index 0000000..61843aa
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/schema-factory.adoc
@@ -0,0 +1,133 @@
+= Schema Factory Configuration
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Solr supports two styles of schema: a managed schema and a manually maintained `schema.xml` file.
+When using a managed schema, features such as the xref:indexing-guide:schema-api.adoc[] and xref:indexing-guide:schemaless-mode.adoc[] are available.
+When using `schema.xml`, the only way changes can be made to Solr's schema is by manually editing the file.
+
+== <schemaFactory> in solrconfig.xml
+
+The `<schemaFactory>` in `solrconfig.xml` defines whether your system will use a managed schema or `schema.xml`.
+
+[source,xml]
+----
+<config>
+ <schemaFactory>
+ ...
+ </schemaFactory>
+</config>
+----
+
+
+
+While the "read" features of the Schema API are supported for all schema types, support for making schema modifications programmatically depends on the `<schemaFactory/>` in use.
+
+== Schema Factories
+
+=== ManagedIndexSchemaFactory
+
+When a `<schemaFactory/>` is not explicitly declared in a `solrconfig.xml` file, Solr implicitly uses a `ManagedIndexSchemaFactory`, which is by default `"mutable"` (editable) and keeps schema information in a `managed-schema.xml` file.
+
+Using the Managed Schema is required to be able to use the Schema API to modify your schema.
+However, using Managed Schema does not mean you are also using Solr in Schemaless Mode (or "schema guessing" mode).
+
+Schemaless mode requires enabling the Managed Schema if it is not already, but full schema guessing requires additional configuration as described in the section xref:indexing-guide:schemaless-mode.adoc[].
+
+Below is an example of a `schemaFactory` that reflects Solr's defaults:
+
+[source,xml]
+----
+ <schemaFactory class="ManagedIndexSchemaFactory">
+ <bool name="mutable">true</bool>
+ <str name="managedSchemaResourceName">managed-schema.xml</str>
+ </schemaFactory>
+----
+
+The defaults can be overridden by explicitly configuring `ManagedIndexSchemaFactory` and changing one of the following options:
+
+`mutable`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `true`
+|===
++
+Controls whether changes may be made to the schema data.
+This must be set to `true` to allow edits to be made with the Schema API.
++
+With the default configuration shown above, you could use the xref:indexing-guide:schema-api.adoc[] to modify the schema as much as you want, and then later change the value of `mutable` to `false` to "lock" the schema in place and prevent future changes.
+
+`managedSchemaResourceName`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `managed-schema.xml`
+|===
++
+The name of the schema file.
+The name can be anything other than `schema.xml`, as that name is reserved for the `ClassicIndexSchemaFactory`.
+
+=== ClassicIndexSchemaFactory
+
+An alternative to using a managed schema is to explicitly configure a `ClassicIndexSchemaFactory`.
+This requires the use of a `schema.xml` file, and disallows any programatic changes to the Schema at run time.
+The `schema.xml` file must be edited manually and is loaded only when the collection is loaded.
+
+[source,xml]
+----
+ <schemaFactory class="ClassicIndexSchemaFactory"/>
+----
+
+This option takes no parameters.
+
+== Changing Schema Factories
+
+=== Switching from schema.xml to Managed Schema
+
+If you have an existing Solr collection that uses `ClassicIndexSchemaFactory`, and you wish to convert to use a managed schema, you can simply modify the `solrconfig.xml` to specify the use of the `ManagedIndexSchemaFactory`.
+
+Once Solr is restarted and it detects that a `schema.xml` file exists, but the `managedSchemaResourceName` file (i.e., "`managed-schema.xml`") does not exist, the existing `schema.xml` file will be renamed to `schema.xml.bak` and the contents re-written to the managed schema file.
+
+If you look at the resulting file, you'll see this at the top of the page:
+
+[source,xml]
+----
+<!-- Solr managed schema - automatically generated - DO NOT EDIT -->
+----
+
+You are now free to use the xref:indexing-guide:schema-api.adoc[] to make changes, and remove the `schema.xml.bak`.
+
+=== Switching from Managed Schema to schema.xml
+
+If you have started Solr with managed schema enabled and you would like to switch to manually editing a `schema.xml` file, you should take the following steps:
+
+. Rename the `managed-schema.xml` file to `schema.xml`.
+. Modify `solrconfig.xml` to replace the `schemaFactory` class.
+.. Remove any `ManagedIndexSchemaFactory` definition if it exists.
+.. Add a `ClassicIndexSchemaFactory` definition as shown above
+. Reload the core(s).
+
+If you are using SolrCloud, you may need to modify the files via ZooKeeper.
+The `bin/solr` script provides an easy way to download the files from ZooKeeper and upload them back after edits.
+See the section xref:deployment-guide:solr-control-script-reference.adoc#zookeeper-operations[ZooKeeper Operations] for more information.
+
+[TIP]
+====
+To have full control over your `schema.xml` file, you may also want to disable schema guessing, which allows unknown fields to be added to the schema during indexing.
+The properties that enable this feature are discussed in the section xref:indexing-guide:schemaless-mode.adoc[].
+====
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/script-update-processor.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/script-update-processor.adoc
new file mode 100644
index 0000000..0f944b7
--- /dev/null
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/script-update-processor.adoc
@@ -0,0 +1,297 @@
+= Script Update Processor
+// 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
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The {solr-javadocs}/modules/scripting/org/apache/solr/scripting/update/ScriptUpdateProcessorFactory.html[ScriptUpdateProcessorFactory] allows Java scripting engines to be used during Solr document update processing, allowing dramatic flexibility in expressing custom document processing logic before being indexed.
+
+It has hooks to the commit, delete, rollback, etc indexing actions, however add is the most common usage.
+It is implemented as an UpdateProcessor to be placed in an UpdateChain.
+
+TIP: This used to be known as the _StatelessScriptingUpdateProcessor_ and was renamed to clarify the key aspect of this update processor is it enables scripting.
+
+The script can be written in any scripting language supported by your JVM (such as JavaScript), and executed dynamically so no pre-compilation is necessary.
+
+WARNING: Being able to run a script of your choice as part of the indexing pipeline is a really powerful tool, that I sometimes call the _Get out of jail free_ card because you can solve some problems this way that you can't in any other way.
+However, you are introducing some potential security vulnerabilities.
+
+== Installing the ScriptingUpdateProcessor and Scripting Engines
+
+The scripting update processor lives in the module `/modules/scripting`, and you need to explicitly add it to your Solr setup.
+
+Java 11 and previous versions come with a JavaScript engine called Nashorn, but Java 12 will require you to add your own JavaScript engine.
+Other supported scripting engines like JRuby, Jython, Groovy, all require you to add JAR files.
+
+Learn more about adding the `modules/scripting/lib/solr-scripting-*.jar` file, and any other needed JAR files (depending on your scripting engine) into Solr's xref:libs.adoc#lib-directories[Lib Directories].
+
+== Configuration
+
+[source,xml]
+----
+<updateRequestProcessorChain name="script">
+ <processor class="org.apache.solr.scripting.update.ScriptUpdateProcessorFactory">
+ <str name="script">update-script.js</str>
+ </processor>
+ <!-- optional parameters passed to script
+ <lst name="params">
+ <str name="config_param">example config parameter</str>
+ </lst>
+ -->
+ <processor class="solr.LogUpdateProcessorFactory" />
+ <processor class="solr.RunUpdateProcessorFactory" />
+ </updateRequestProcessorChain>
+----
+
+NOTE: The processor supports the defaults/appends/invariants concept for its config.
+However, it is also possible to skip this level and configure the parameters directly underneath the `<processor>` tag.
+
+Below follows a list of each configuration parameters and their meaning:
+
+`script`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+The script file name.
+The script file must be placed in the `conf/` directory.
+There can be one or more "script" parameters specified; multiple scripts are executed in the order specified.
+
+`engine`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Optionally specifies the scripting engine to use.
+This is only needed if the extension of the script file is not a standard mapping to the scripting engine.
+For example, if your script file was coded in JavaScript but the file name was called `update-script.foo`, use `javascript` as the engine name.
+
+`params`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Optional parameters that are passed into the script execution context.
+This is specified as a named list (`<lst>`) structure with nested typed parameters.
+If specified, the script context will get a "params" object, otherwise there will be no "params" object available.
+
+== Script Execution Context
+
+Every script has some variables provided to it.
+
+`logger`::
+Logger (org.slf4j.Logger) instance.
+This is useful for logging information from the script.
+
+`req`::
+{solr-javadocs}/core/org/apache/solr/request/SolrQueryRequest.html[SolrQueryRequest] instance.
+
+`rsp`::
+{solr-javadocs}/core/org/apache/solr/response/SolrQueryResponse.html[SolrQueryResponse] instance.
+
+`params`::
+The "params" object, if any specified, from the configuration.
+
+== Examples
+
+The `processAdd()` and the other script methods can return false to skip further processing of the document.
+All methods must be defined, though generally the `processAdd()` method is where the action is.
+
+Here's a URL that works with the techproducts example setup demonstrating specifying the "script" update chain: `http://localhost:8983/solr/techproducts/update?commit=true&stream.contentType=text/csv&fieldnames=id,description&stream.body=1,foo&update.chain=script` which logs the following:
+
+[source,text]
+----
+INFO: update-script#processAdd: id=1
+----
+
+You can see the message recorded in the Solr logging UI.
+
+=== Javascript
+
+Note: There is a JavaScript example `update-script.js` as part of the "techproducts" configset.
+Check `solrconfig.xml` and uncomment the update request processor definition to enable this feature.
+
+[source,javascript]
+----
+function processAdd(cmd) {
+
+ doc = cmd.solrDoc; // org.apache.solr.common.SolrInputDocument
+ id = doc.getFieldValue("id");
+ logger.info("update-script#processAdd: id=" + id);
+
+// Set a field value:
+// doc.setField("foo_s", "whatever");
+
+// Get a configuration parameter:
+// config_param = params.get('config_param'); // "params" only exists if processor configured with <lst name="params">
+
+// Get a request parameter:
+// some_param = req.getParams().get("some_param")
+
+// Add a field of field names that match a pattern:
+// - Potentially useful to determine the fields/attributes represented in a result set, via faceting on field_name_ss
+// field_names = doc.getFieldNames().toArray();
+// for(i=0; i < field_names.length; i++) {
+// field_name = field_names[i];
+// if (/attr_.*/.test(field_name)) { doc.addField("attribute_ss", field_names[i]); }
+// }
+
+}
+
+function processDelete(cmd) {
+ // no-op
+}
+
+function processMergeIndexes(cmd) {
+ // no-op
+}
+
+function processCommit(cmd) {
+ // no-op
+}
+
+function processRollback(cmd) {
+ // no-op
+}
+
+function finish() {
+ // no-op
+}
+----
+
+=== Ruby
+Ruby support is implemented via the https://www.jruby.org/[JRuby] project.
+To use JRuby as the scripting engine, add `jruby.jar` to Solr.
+
+Here's an example of a JRuby update processing script (note that all variables passed in require prefixing with `$`, such as `$logger`):
+
+[source,ruby]
+----
+def processAdd(cmd)
+ doc = cmd.solrDoc # org.apache.solr.common.SolrInputDocument
+ id = doc.getFieldValue('id')
+
+ $logger.info "update-script#processAdd: id=#{id}"
+
+ doc.setField('source_s', 'ruby')
+
+ $logger.info "update-script#processAdd: config_param=#{$params.get('config_param')}"
+end
+
+def processDelete(cmd)
+ # no-op
+end
+
+def processMergeIndexes(cmd)
+ # no-op
+end
+
+def processCommit(cmd)
+ # no-op
+end
+
+def processRollback(cmd)
+ # no-op
+end
+
+def finish()
+ # no-op
+end
+----
+
+==== Known Issues
+
+The following in JRuby does not work as expected, though it does work properly in JavaScript:
+
+[source,ruby]
+----
+# $logger.info "update-script#processAdd: request_param=#{$req.params.get('request_param')}"
+# $rsp.add('script_processed',id)
+----
+
+=== Groovy
+
+Add JARs from a Groovy distro's `lib/` directory to Solr.
+All JARs from Groovy's distro probably aren't required, but more than just the main `groovy.jar` file is needed (at least when this was tested using Groovy 2.0.6)
+
+[source,groovy]
+----
+def processAdd(cmd) {
... 165845 lines suppressed ...