Upgrading to v5.0.0

wit-cms@v5.0.0 is backwards-incompatible with prior versions. To upgrade to v5.0.0, you will need to make the following modifications to an existing project:

• Change the wit object initialization code
• Change the wit initialization configs

Additionally, several new features are now available.

Change the wit object initialization code

wit object initialization is now synchronous rather than asynchronous. Prior initialization code looked like this:

// ... (dependencies)

// initialize an express object
var app = express();

// ... (express bootstrapping)

// initialize a wit object
Wit(app, config, function(err, wit) {
  
});

This should now be rewritten thusly:

// ... (dependencies)

// initialize an express object
var app = express();

// ... (express bootstrapping)

// initialize a wit object
const wit = Wit(app, config);

Change the wit initialization configs

Some configuration parameters have been moved and renamed for the sake of cleanliness. It's easy to see which properties need to be moved where by examining the old configs vis-a-vis the new:

v4 configs

{

  path: {
    // path at which data may be retrieved asynchronously
    asyncRoot: '/async/',

    // 404 page
    notFoundPage: '/not-found',
  },
  
  // page configs
  pages: {
    dir: './pages/',
  },

  // post configs
  posts: {
    dir      : './posts/',
    excerpt  : {
      length : 1,
      units  : 'paragraphs',
    },
    perPage  : 5,
  },

  // search configs
  search: {
    boost: {
      title       : 10,
      description : 5,
      excerpt     : 5,
      content     : 0,
      author      : 0,
    },
  },

  // remarkable (markdown parser) configs
  remarkable: {
    html    : true,
    linkify : true,
  },

  // misc configs
  dateFormat         : 'D MMMM YYYY',
  readMoreSeparator  : '<!--more-->',
  markdownExtensions : [ 'markdown', 'md' ],
  enableAsyncRoutes  : true,
};

v5 configs

{

  // build hooks
  build: {

    // markdown configs
    markdown: {
      extensions: [ 'markdown', 'md' ], // markdown file extensions

      // remarkable (markdown parser) configs
      remarkable: {
        html    : true,                 // allow html tags in source
        linkify : true,                 // auto-link urls?

        // implement code syntax-highlighting via highlightjs
        highlight: function (str, lang) {
          if (lang && hljs.getLanguage(lang)) {
            try {
              return hljs.highlight(lang, str).value;
            } catch (err) {}
          }
          try {
            return hljs.highlightAuto(str).value;
          } catch (err) {}
          return '';
        }
      },
    },

    /*
    // function to invoke before initializing the wit object
    before: function (configs, app, wit) {

    },

    // function to invoke after the wit object has been initialized
    after: function (configs, app, wit) {

    },
    */
  },
  
  // page configs
  pages: {
    dir      : './pages/',             // directory in which markdown page files are located
    notFound : '/not-found',           // 404 "not found" page url
  },

  // post configs
  posts: {
    dir      : './posts/',              // directory in which markdown page files are located
    excerpt  : {                        // rules for generating excerpts
      length : 1,
      units  : 'paragraphs',
    },
    perPage  : 5,                       // number of posts to display on the blog index page
    readMoreSeparator : '<!--more-->',  // separator between excerpt and remaining content
    dateFormat        : 'D MMMM YYYY',  // article date format
  },

  // search configs
  search: {                             // lunrjs search configs
    boost: {                            // ranking weights per post property
      title       : 10,
      description : 5,
      excerpt     : 5,
      content     : 0,
      author      : 0,
    },
  },

  // async routes
  async: {
    enabled : true,                    // enable async routes?
    root    : '/async/',               // prefix at which async routes are available
  },
};

New Features

The following new features are now available:

searchable front-matter property

A new searchable page front-matter property (a boolean) provides a mechanism for excluding specified pages from search results.

url front-matter property

A new url page front-matter property provides a mechanism for explicitly specifying a page's URL. (Among other uses, this makes it easier to specify an index page without relying on Express redirects.)

in-built syntax-highlighting

Syntax-highlighting now comes pre-configured "out-of-the-box" via highlight.js.