diff --git a/config/intro-template.md.js b/config/intro-template.md.js new file mode 100644 index 000000000..2f319d9f7 --- /dev/null +++ b/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 + +\`\`\` + +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 +` diff --git a/tasks/docs/build.js b/tasks/docs/build.js index 83ebbeecc..577ac9dab 100644 --- a/tasks/docs/build.js +++ b/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(