Searching Forrest-built documentation

Forrest provides a simple interface to the Google search engine. It invokes Google Advanced Search and limits the search scope to the domain of your choice. Since the actual search functionality is implemented on Google's end, you do not need any additional capability on your Forrest server (which may well be a simple static web server serving content generated with forrest site).

To use Google SiteSearch in your Forrest application, open your skinconf.xml file. By default this file is in the src/documentation subdirectory of your Forrest repository root. Find the <search> element; it should be near the top of the file. If the element does not exist, create it below the <skinconfig> opening tag. If there is any attribute named provider, remove it. The element should look similar to this:

<search name="MyProject"
	domain="myproject.com"/>
      

Then, build your Forrest documentation and open it using your favorite web browser. You are now invited to peruse the search box (most skins render this in the top-right corner). Google's search results will be displayed in a new browser window.

Needless to say, for this to work your content must be accessible to Google's indexing robot. It can't be stored on a server which is only locally accessible, or which requires authentication. In addition, the content index is created and updated at a time of Google's choosing. However, the search is fast and search precision is usually excellent. So if your Forrest content is placed on a busy, popular public web server, Google search is probably the best choice.

Lucene is a high-performance, full-text search engine built entirely in Java. To use Lucene-based search with your Forrest documentation, you will need to run Forrest in a Java servlet environment (such as Tomcat or Jetty). Lucene-based searching will not work in a static site generated with the 'forrest site' command.

In order to enable Lucene-based full-text search in your Forrest application, you must first edit your skinconf.xml file. Locate the <search> element. If the element does not exist, insert it right underneath the <skinconfig> opening tag. Add an attribute named provider with a value of lucene, so that the element looks similar to this:

<search name="MyProject" domain="myproject.com"
	provider="lucene"/>
      

Next, create and run your Forrest webapp. This may mean simply invoking forrest run, or building and bundling a servlet webapp (with forrest webapp), and then deploying it to your servlet container.

You can now build a Lucene search index by pointing your web browser at http://localhost:8888/lucene-update.html. This generates the search index and provides some information about the index generation process.

Now you can utilize the full-text search box, located in the top-right corner of the rendered Forrest pages. Search results will be displayed in the same browser window and will look remarkably similar to the rest of your Forrest documents.

Unlike with Google SiteSearch, the indexing information retrieved by Lucene is stored on your own server, access to which you may limit to users in your own organization. Likewise, you may update or recreate the Lucene index at any time and at your own discretion. So if you aren't making your Forrest-built documentation publicly available, and you're able to run Forrest on a Java-enabled web server, Lucene search is probably right for you.

If you are convinced your users don't need any full-text search capability whatsoever, you may disallow displaying the search box entirely. You may also wish to do so if you're keeping Forrest-built content on a restricted server (meaning you can't use Google), while at the same time not having any usable servlet-capable web server at your disposal (meaning you can't use Lucene, either).

To disable full-text search completely, open the skinconf.xml file and remove (or comment out) the entire <search> element.