Getting Started

Doxicity is designed to be used programmatically. It’s API is simple enough to add to an existing build script, but you can also put it in a standalone script if you prefer!

This guide will show you how to install Doxicity, configure a website, and publish it.

Installation

To install Doxicity, run the following command. This assumes you have Node.js installed.

npm i doxicity

          

          
        

Now that Doxicity is installed, you’re ready to configure it.

Configuration

The config tells Doxicity what files to publish, where to publish them, what data to provide, and more. Providing a config is optional, but strongly recommended. Your config must be passed in when the Doxicity instance is created.

Here’s what a full config with all options looks like. The comments describe more about each option, but you can also view more details on the configuration page.

import Doxicity from 'doxicity';

const __dirname = new URL('.', import.meta.url).pathname;

//
// Configure it
//
const dox = new Doxicity({
  // The directory containing markdown files to publish. For best results, use
  // a fully resolved path.
  source: Doxicity.resolve(__dirname),

  // The directory where HTML files will be generated. For best results, use a
  // fully resolved path.
  destination: Doxicity.resolve(__dirname, '_site'),

  // The base URL that the website will be published to. To generate fully
  // qualified URLs, make sure this starts with "http://" or "https://".
  baseUrl: 'https://example.com/',

  // The name of the directory that contains layouts. Must be relative to the
  // project's source directory. This is where *.hbs layouts are expected to be
  // found. Defaults to "layouts".
  layouts: 'layouts',

  // The name of the directory that contains partials. Must be relative to the
  // project's source directory. This is where *.md and *.hbs partials are
  // expected to be found. Defaults to "partials".
  partials: 'partials',

  // The name of the directory that contains the project's assets such as
  // images, styles, scripts, etc. Must be relative to the project's source
  // directory. This directory will be copied to the output directory as-is on
  // publish. Nothing will be copied unless this option is set.
  assets: '',

  // Any data you put here will be available in your HTML and markdown files
  // through the use of Handlebars expressions. If you use front matter in your
  // markdown files, that data will be merged with this data with the front
  // matter taking precedence.
  data: {},

  // When true, Doxicity will delete the destination directory before writing
  // anything to it.
  cleanBeforePublishing: false,

  // Optional plugins to customize how pages are published. Plugins are
  // executed in the order they're provided in your configuration.
  plugins: [],

  // Optional helpers to extend Handlebars with. To learn more about what
  // helpers are and how they work, refer to the Handlebars documentation.
  // https://handlebarsjs.com/guide/expressions.html#helpers
  helpers: [],

  // A callback function that accepts a filename. If this function returns
  // `true`, the target file will be published. If it returns `false`, the
  // file will be ignored.
  filterPages: () => true,

  // The extension to use when publishing pages. Defaults to `html`.
  pageExtension: 'html'
});

//
// Publish it
//
dox
  .publish()
  .then(result => {
    console.log(
      `Pages published: ${result.pages.length}\n` +
        `Assets copied: ${result.assets.length}\n` +
        `Duration: ${result.timeToPublish}ms\n`
    );
  })
  .catch(err => {
    console.log(err.message);
  });

          

          
        

The call to dox.publish() in the example above tells Doxicity to process and publish your website. At this time, assets are copied, markdown files are processed, plugins are run, and files are written to the destination folder provided in your config.

Make sure to check out the pages on data, plugins, layouts, partials, helpers, and publishing for more information about how everything works.