Configuration

This is a guide to configuring your WikiDB installation. WikiDB is configured using an XML config file located in ~/.config/wikidb/config.xml or in /etc/wikidb/config.xml. If the configuration file cannot be found in ~/.config/wikidb/config.xml, it will be retrieved from /etc/wikidb/config.xml. If it cannot be found in either location, none of the functions of the software will work. In case your local config files are not accessible, you may copy the content from here. If the config files are too malformed, the software may fail to locate the necessary information and will not function.

Default Config File

This is the default config file that you will find after a new WikiDB install:

<?xml version="1.0" encoding="UTF-8"?>

<config>
    <defaults>
        <databaseDefault>main</databaseDefault>
        <wikiDefault>archwiki</wikiDefault>
    </defaults>

    <databases>
        <database>
            <name>main</name>
	        <root>~/.local/share/wikidb</root>
        </database>
    </databases>
    
    <wikis>
        <wiki>
            <name>archwiki</name>
	        <url>https://wiki.archlinux.org/title/{}</url>
            <downloadReferencedImage>false</downloadReferencedImage>

            <injections>

                <inject>
			        <destination>//head</destination>
                    <path>/etc/wikidb/wikis/archwiki/style</path>
                    <place>before</place>
                </inject>

                <inject>
                    <destination>//body</destination>
                    <path>/etc/wikidb/wikis/archwiki/header</path>
                    <place>before</place>
                </inject>

            </injections>

            <removals>
                <remove>
                    <id>archnavbar</id>
                </remove>
                <remove>
                    <id>mw-sidebar-button p-search p-vector-user-menu-overflow p-personal mw-sidebar-checkbox mw-panel-toc mw-navigation vector-toc-collapsed-checkbox p-lang-btn left-navigation right-navigation catlinks</id>
                </remove>
                <remove>
                    <tag>script</tag>
                </remove>
            </removals>
        </wiki>
    </wikis>
</config>

The config file is separated into three parts: defaults, databases, and wikis. The defaults section handles the default database and wiki to use when they are not specified. The databases section handles configuring databases across the system. The wikis section handles configuration of wikis.

Configuring Databases

Databases are registered using the <database> tag inside of the <databases> tag inside of the root tag. This is the format for an entry in the <databases> tag:

<database>
    <name>name</name>
    <root>/path/to/db/</root>
</database>

The name element must contain a string with no special characters, and the root element must contain a path to the root directory where the database should be stored. This must be a valid directory on the system. Ideally, the path should be relative to the root directory and be accessible to non-root users.

Configuring Wikis

Wikis are registered using the <wiki> tag in the <wikis> element inside the root tag. This is the format for an entry in the <wikis> tag:

<wiki>
    <name>name</name>
    <url>https://path.to/web/page</url>
    <downloadReferencedImage>false</downloadReferencedImage>

    <injections/>
    <removals/>
</wiki>

The name tag must contain a valid filesystem name and be all lowercase. The url tag represents the path to the place where the pages should be downloaded from. It should be formatted like a regular uri and should contain "{}" wherever the page name to target should be put. The "{}" will be replaced with the command-line argument representing the page to download (for example, the format for the Arch Wiki is "https://wiki.archlinux.org/title/{}" because page names would take the place of "{}"). The downloadReferencedImage tag is a not-yet-functional element that tells the system whether to download images referenced by HTML <img> tags and reroute the src attribute of them to point to the downloaded media. This feature will come later. Finally, the injections and removals tags represent content to insert into or remove from the downloaded HTML.

Note that when pages are sanitized, any <a> tags that contain relative links (i.e., starting with a slash) and match the URI format referenced in the wiki configuration are rerouted to have the <a> tag's href attribute point to wherever the appropriate linked page should be located if it is downloaded.

Configuring Injections

Injections are placed in the <injections> tag of a wiki configuration. They are formatted like so:

<inject>
    <destination>xpath</destination>
    <path>/path/to/html</path>
    <place>before</place>
</inject>

The destination tag should contain an XPath expression representing the parent tag under which the injected HTML should be put. The path tag represents the path to the file that contains the HTML to inject. Right now, this is the only supported mode of sourcing injection HTML. The place tag may be either "before" or "after." This represents whether the injected HTML should be put as a child before the first child or after the last child.

Configuring Removals

Removals are placed in the <removals> tag of a wiki configuration. They are formatted like so:

<remove>
    <id>id</id>
    <xpath>//thing</xpath>
    <tag>tag</tag>
</remove>

Each removal may have ONE of the listed three tag options. The tag tag removes all occurrences of the specified tag within the HTML. The id tag removes one tag that matches the ID provided. The xpath tag removes all tags that match the specified XPath expression. Note that all removals are completed BEFORE any injections. This means that anything specified in removals will not be removed from injected HTML.