VuFind ships with aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/vufind-org/vufind/llms.txt
Use this file to discover all available pages before exploring further.
local/ directory that is the designated home for every institutional customization. Rather than editing files inside the VuFind source tree, you copy only the files you need to change into local/ and modify them there. VuFind’s file-resolution logic checks local/ first and falls back to the core installation, so your overrides take precedence transparently.
As the local/README.txt in the VuFind repository states:
All of your local configurations and customizations belong in this directory and its subdirectories. Rather than modifying core VuFind files, you should copy them here and modify them within the local directory. This will make upgrades easier.
How the override system works
When VuFind looks up any configuration file, template, or language string, it checks the local directory path before the module or core path. The first matching file wins.git pull or a package upgrade, because your customizations live outside the tracked source tree.
The local/ directory structure
Thelocal/ directory mirrors the structure of the core VuFind installation for configuration and languages, and mirrors the theme directory for templates:
local/
cache/
config/
vufind/
harvest/
DirLocations.ini.dist
README.txt
local/languages/ for translation overrides and local/themes/ if your deployment places custom themes there rather than in the main themes/ directory.
Overriding configuration files
Identify the file to override
All VuFind configuration files live in
config/vufind/. Find the file that contains the setting you want to change. The main configuration file is config/vufind/config.ini.Commonly overridden configuration files
config.ini — main site settings
config.ini — main site settings
Controls site title, theme, language, ILS connection, authentication, and hundreds of other global settings. The
[Site] section is the most frequently customized.local/config/vufind/config.ini
searches.ini — search behavior
searches.ini — search behavior
Defines available search handlers, sort options, result limits, and facets for the primary Solr search backend.
facets.ini — facet configuration
facets.ini — facet configuration
Controls which facets appear on search results pages, their labels, and their display order.
RecordTabs.ini — record detail tabs
RecordTabs.ini — record detail tabs
Configures which tabs (Holdings, Description, Staff View, etc.) appear on individual record pages and in what order.
permissions.ini — access control
permissions.ini — access control
Defines role-based access rules for admin pages, debug mode, and other protected features.
ILS drivers — catalog integration
ILS drivers — catalog integration
Connection settings for your integrated library system go in a driver-specific config file such as
Horizon.ini, Symphony.ini, or Folio.ini.Overriding templates
Templates control the HTML markup for every page in VuFind. They are.phtml files (Laminas/Zend view scripts) located under a theme’s templates/ directory. VuFind resolves templates by walking the active theme’s inheritance chain, so you can override a template at either the theme level or at the local level.
- Override in your custom theme
- Override in local/themes/
The preferred approach: place the modified template inside your theme’s
templates/ directory. This keeps overrides scoped to the theme.bootstrap5 theme provides templates for every part of the interface. Key subdirectories include:
| Directory | Contains |
|---|---|
templates/layout/ | Page frame, header, footer wrappers |
templates/header.phtml | Top navigation and search bar |
templates/footer.phtml | Footer content |
templates/search/ | Search home, results, and related pages |
templates/record/ | Individual record detail pages |
templates/myresearch/ | User account pages |
templates/content/ | Static content pages |
templates/Auth/ | Login and registration forms |
templates/RecordTab/ | Individual record tabs (Holdings, Description, etc.) |
Overriding language strings
Language files live inlanguages/ and use a simple INI key = "value" format. To customize displayed text, copy the relevant language file into local/languages/ and change only the strings you need.
local/languages/en.ini
You only need to include the keys you want to override. VuFind merges
local/languages/en.ini on top of languages/en.ini, so any key not present in your local file falls back to the core translation.Best practices for upgrade safety
Keep local/ outside version control of the core
Do not commit your
local/ changes into the main VuFind Git repository. Instead, maintain a separate Git repository (or subtree) for local/, or use a deployment tool that manages it independently.Override only what you must
Every file you copy into
local/ or into a custom theme becomes a file you are responsible for maintaining. Where possible, use configuration settings rather than template overrides, because config files are far easier to merge during upgrades.Document your changes
Add comments inside your local files explaining why you overrode that particular setting or template block. Future maintainers (and future you) will thank you.
local/config/vufind/config.ini
Review upstream diffs on upgrade
After upgrading VuFind, diff your local overrides against the new core files to identify anything that needs to be merged:
Example: overriding the search results page title
Here is a complete walkthrough of overriding one specific template to add your institution’s name to search result page titles.Make a targeted edit
Open the copied template and modify only the specific block you need. Leave the rest of the file unchanged so that future merges are as small as possible.