Customizing Indexy

Indexy offers various ways you can change how its look and behavior.

Customizing the Appearance

Indexy comes with its own CSS file to style highlighted terms and other glossary-related elements. It is located in the plugin’s style folder, and is automatically loaded into your website when the plugin is enabled. The default stylesheet is designed to work with WordPress’ TwentyFifteen theme; if you are using a different theme, it may or may not look good. Fortunately, with basic CSS knowledge, you can customize how Indexy highlights terms, as well as the appearance of the widgets and content generated by shortcodes.

You can edit the indexy.css file using any basic text editor, such as Notepad, or a more advanced editor with code highlighting capabilities (my personal favorite is Sublime Text). Each section of the file is documented, explaining what that portion does; this way, it should be easy to locate the part you need to edit in order to tailor the appearance to your preferences.

Preserving Your Changes

If you wish to customize the appearance, it is recommended that you make a copy of the indexy.css file, instead of editing the one inside the plugin’s folder. This way, your changes are preserved whenever you install an update to the plugin.

When the theme you use on your website has a file named indexy.css in the theme’s main folder, that file will be loaded instead of the CSS file that Indexy provides. Alternatively, if you wish to include the styling for glossary elements in the theme’s main style.css file (this would reduce the number of requests a web browser has to make to the server in order to completely load the page), and omit the indexy.css file altogether, there are two things you can do:

  • On Indexy’s settings page, set the Include CSS file option to No. With this setting, Indexy will not try to load any additional stylesheets.
  • Create an empty file named indexy.css in the theme’s main folder. Indexy will detect that the file is empty, and not ask WordPress to load it at all, nor will it load the default copy that ships with the plugin itself. This method does not require the website administrator to modify any settings, and is recommended if you’re creating a theme that you redistribute. Note that the file has to be empty (i.e., it is 0 bytes in size) for this method to work.

Customizing the Glossary Article Page

In your theme, you can customize the appearance of glossary pages by creating a file named single-glossary.php in the theme’s main folder. Whenever a glossary page is requested, WordPress will use that template file to generate the page, instead of the regular post template.

A good starting point for creating your own customized template may be to make a copy of the theme’s page.php template. Some modifications you may want to consider include:

  • Display a list of synonyms for the term under the page title. You can use the Indexy::get_synonyms() function to do this; refer to the sample single-glossary.php file for a reference implementation.
  • Remove the post thumbnail, author bio, and previous post/next post links.

Indexy comes with a sample single-glossary.php file, located in the theme folder in Indexy’s plugin folder, that is designed to work with the TwentyFifteen theme. You can simply copy it into the theme’s folder to start using it. The same file may or may not work with other themes.

Customizing Excerpts

If you are more familiar with the internals of WordPress (specifically its use of filters), you can further customize how Indexy generates excerpts of glossary pages. Indexy defines three filters that control the excerpt behavior. These three filters function in a manner identical to the similarly-named filters that WordPress uses when generating excerpts of regular posts and pages.

These filters are:

  • indexy_excerpt_text (can be used to further alter the excerpt text after it has been generated)
  • indexy_excerpt_length (controls the length of the excerpt)
  • indexy_excerpt_more (changes the text of the ‘more…’ link; only used by the indexy_excerpt shortcode)

Note: when a handcrafted excerpt is written for a glossary article, it is always used instead of trying to generate an excerpt, and therefore for those articles these filters cannot override or modify the excerpt.

A Soul Waking