Migration links are out of date

[warpdesign]

All migrations links found in the release pages seem to point to 404.

I'd like to migrate a project that's using Docma 1.x but don't know how to do it.

Example of broken link: CHANGELOG

[warpdesign]

Attempted to updated to v2.x and got an error with my template: it seems the way templates are defined has changed.

I used to have this:

docma-template-foo/
docma-template-foo/docma.template.json
docma-template-foo/docma.template.json
docma-template-foo/js/
docma-template-foo/index.html

Right now it's expecting a node module so crashes in templateBuild trying to require('docma-template-foo') which of course doesn't work since it's not an npm module.

Are there any guides on how to migrate from 1.x to 2.x (and then to 3.x)?

[onury]

Thanks for the heads-up. Updated all change-log links in releases. Essentially all (should) point to the same change-log page though.

Yes. As noted here, templates are now node modules.

Migrating your template for Docma v2+

• Configure the package.json of your module to define the template
• (Optionally) create a main file (i.e.index.js) to hook into the build process.
• Remove the docma.template.json which is obsolete now.
• You can also use docma template init command to initialize a new template and docma template doctor to validate your template for basic checks. See CLI commands section for details.
• See Zebra template repo for an example.
• Note that, as a breaking change; Docma v2 requires your end users to run Node v6 or greater.

Migrating your template for Docma v3+

• Check out the linking logic changes.
• As a breaking change; Docma v3 requires your end users to run Node v8 or greater.

❗️Don't forget to add docma as peer dependency and set the proper Docma version that your template supports. e.g. "docma": ">=2.0.0"

Read more:

• Creating Docma Templates
• General F.A.Q.

[warpdesign]

Thanks for the details.

Started porting my template to v2.

I used to have a compile option in my template json file:

{
    "compile": {
         "js/app.js": "js/app.min.js"
    }

I don't see anything similar for v2 templates: is it gone?

[onury]

Yes, mentioned in change-log for v2. Files should be pre-compiled in order to speed up build process for the end-user.

[onury]

If you need it that way; you can still workaround this by hooking into build process via preBuild() or postBuild() and also use fs and utils or your own functions/modules, though.