feat(docs): add generic intro template

config/intro-template.md.js

@@ -0,0 +1,53 @@
+'use strict'
+const upperFirst = require('lodash.upperfirst')
+const camelCase = require('lodash.camelcase')
+
+function exampleTmpl (example) {
+  if (!example) {
+    return ''
+  }
+
+  return `
+
+## Quick Example
+
+\`\`\`js
+${example}
+\`\`\`
+
+There are more available, so take a look at the docs below for a full list. This documentation aims to be comprehensive, so if you feel anything is missing please create a GitHub issue for it.`
+}
+
+module.exports = (name, url, example) => `
+Installable via  \`npm install --save ${name}\`, it can also be used directly in the browser.
+
+${exampleTmpl(example)}
+
+## Download
+
+The source is available for download from [GitHub](${url}). Alternatively, you can install using npm:
+
+\`\`\`bash
+$ npm install --save ${name}
+\`\`\`
+
+You can then \`require()\` ${name} as normal:
+
+\`\`\`js
+const ${camelCase(name.replace(/-/g, ' '))} = require('${name}')
+\`\`\`
+
+## In the Browser
+${upperFirst(name)} should work in any ES2015 environment out of the box.
+
+Usage:
+
+\`\`\`html
+<script type="text/javascript" src="index.js"></script>
+\`\`\`
+
+The portable versions of ${name}, including \`index.js\` and \`index.min.js\`, are included in the \`/dist\` folder. ${upperFirst(name)} can also be found on [unkpkg.com](https://unpkg.com) under
+
+- https://unpkg.com/${name}/dist/index.min.js
+- https://unpkg.com/${name}/dist/index.js
+`

tasks/docs/build.js

@@ -4,8 +4,23 @@ const pump = require('pump')
 const join = require('path').join
 const docs = require('gulp-documentation')
 const exists = require('path-exists').sync
+const fs = require('fs')
+const gutil = require('gulp-util')
 
 const pkg = require('../../config/user').pkg
+const introTmpl = require('../../config/intro-template.md')
+
+function generateDescription (name) {
+  let example
+  try {
+    example = fs.readFileSync(join(
+      process.cwd(), 'example.js'
+    )).toString()
+  } catch (err) {
+    gutil.log('Warning: No `example.js` found in the root directory.')
+  }
+  return introTmpl(name, pkg.repository.url, example)
+}
 
 module.exports = (gulp) => {
   gulp.task('docs:build', ['clean:docs'], (cb) => {
@@ -16,6 +31,11 @@ module.exports = (gulp) => {
     const configFile = join(process.cwd(), 'documentation.yml')
     if (exists(configFile)) {
       options.config = configFile
+    } else {
+      options.toc = [{
+        name: 'Intro',
+        description: generateDescription(pkg.name)
+      }]
     }
 
     pump(