# Creating the website structure

To build the website structure:

1. On your workstation, create a new directory and change into it. For example, on a Linux system, run:

       $ mkdir ~/docsite
       $ cd ~/docsite

2. Run `publican create_site`, specifying the following parameters:

   - `--site_config` — the name of the configuration file for your site, with the filename extension `.cfg`

   - `--db_file` — the name of the SQLite database file for your site, with the filename extension `.db`

   - `--toc_path` — the path to the directory in which you will place your documents

   On a computer with an operating system other than Linux, also set:

   - `--tmpl_path` — the path to the `templates/` directory of your Publican installation. On computers with Windows operating systems, this is typically `%SystemDrive%\%ProgramFiles%\Publican\templates`.

   For example:

       $ publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs

   You might give names to the site configuration file and database file that help you to recognize the site to which they belong. For example, for the FooMaster documentation site, you might call these files `foomaster.cfg` and `foomaster.db`. You can set `--toc_path` to whatever you choose.

3. Edit the site configuration file to specify the name of the site, the web host, and optionally, search parameters, default language, dump file settings, and update settings for the site:

   1. Specify the title with the `title` parameter, for example:

          title: "Foomaster Documentation"

      Normally, visitors to your website do not see this title because the site's JavaScript redirects them to a homepage. However, this title is likely to be found and indexed by search engines.

   2. Specify the web host with the `host` parameter as a full URL, including the protocol (for example, `http://`). For example:

          host: http://docs.example.com

      Publican uses the value set for `host` to construct the URLs in the XML `Sitemap` that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.

   3. Optionally, construct a search engine query to use with the search box in the navigation menu and specify the entire content of a HTML `<form>` with the `search` parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the `host` parameter.

      For example, to construct a Yahoo! search limited to `docs.example.com`, set:

          search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'

      Refer to the documentation of your chosen search engine for details of how to construct custom searches.

      If you set `value="###Search###"` in the code for a submit button, Publican uses the word `Search` on the button, localized into any language that Publican supports.

      ## Important — the search parameter is not validated

      Publican does not validate the `search` parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.

   4. Optionally, set the default language of the website. Publican creates a separate, translatable navigation menu for each language in which you publish documentation. However, if a document is not available in a particular language, Publican links visitors to the untranslated version of that document. To specify the default, untranslated language for the site, set `def_lang` with a language code. For example:

          def_lang: fr-FR

      With `def_lang` set to `fr-FR`, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.

   5. Optionally, configure a dump file for the website. Publican can output an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The file is updated whenever a book is installed or removed from the site, or the $ `publican update_site` command is run. Configure the `dump`, `dump_file`, and `zip_dump` parameters as follows:

      `dump`

        Set `dump: 1` to enable the dump file function. This parameter defaults to `0` (off).

      `dump_file`

        Set `dump_file: name` to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to `/var/www/html/DUMP.xml`.

      `zip_dump`

        Set `zip_dump: 1` to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to `0` (off).

      Refer to for a description of the contents of the dump file.

   6. Optionally, specify the web style with the `web_style`.

      web_style: 1

        The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)

      web_style: 2

        The website includes a breadcrumb-like navigation bar across the top of the documentation.

      The web style set for your site must match the web style set for your content. For example, if you set `web_style: 2` for your website, you need to have `web_style: 2` set in each of the books that you want to install on the site. Consider setting this parameter in the `defaults.cfg` or `overrides.cfg` files of the brands that you intend to use with this site.

   7. Optionally, specify that the site tables of contents will be updated manually with the `manual_toc_update` parameter, for example:

          manual_toc_update: 1

      Normally, Publican updates the site's tables of contents every time a documentation package is added or removed. On a site with a large number of documents on it (more than a few hundred), or where documents are updated very frequently (dozens of updates per week), this process is very demanding on a server. On a large or busy site, we recommend that you set this parameter and then periodically update the tables of contents with the $ `publican update_site` command.

   8. Optionally, override the default JavaScript for the site with the `toc_js` parameter, for example:

          toc_js: "mybrand/scripts/megafoo.js"

      This file will be symlinked as `toc_path`/toc.js with the $ `publican update_site` command. This path should be relative to the `toc_path` parameter.

4. Create an empty file named `site_overrides.css` in the directory that you specified with `doc_path` (the directory that contains `interactive.css` and the various language directories). If you want to use site-specific styles to override those provided by `interactive.css`, you can add a `site_overrides.css` to the document that provides the site home page — refer to . If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, change into the directory that you specified with `doc_path` and run:

       $ touch site_overrides.css

5. Build and install each brand, including the Publican `common` brand.

   1. Change into the directory that holds the source for the brand.

          $ cd brandsrc_dir

   2. Build the brand.

          $ publican build --formats=xml --langs=all --publish

   3. Install the brand on your website.

          $ publican install_brand --web --path=path_to_site_root_dir

      Perform these steps for all brands.

6. Update the site.

       $ publican update_site

To make Publican refresh the site structure at any time, run:

    $ publican update_site --site_config path_to_site_configuration_file.cfg