gulp plugin for angularjs documentation

Downloads in past


95570.3.08 years ago10 years agoMinified + gzip package size for gulp-ngdocs in KB


Gulp plugin for building AngularJS like documentation. This is inspired from grunt-ngdocs.


npm install gulp-ngdocs --save-dev


Create a ngdocs gulp task
gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs');
  return gulp.src('path/to/src/*.js')
Create a ngdocs gulp task with options
gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs');
  var options = {
    scripts: ['../app.min.js'],
    html5Mode: true,
    startPage: '/api',
    title: "My Awesome Docs",
    image: "path/to/my/image.png",
    imageLink: "",
    titleLink: "/api"
  return gulp.src('path/to/src/*.js')

To use a different AngularJS version pass angular and angular-animate files in scripts.
gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs');
  var options = {
    /* pass both .min.js and files for angular and angular-animate */
    scripts: [

  If you choose to use the remote links pass in the .min.js links for angular and angular-animate

  var options = {
    scripts: [
  return gulp.src('path/to/src/*.js')

If you would like to divide your documentation into different sections, use gulpDocs.sections instead of gulp.src.
gulp.task('ngdocs', [], function () {
  var gulpDocs = require('gulp-ngdocs');
  var options = {
  return gulpDocs.sections({
    api: {
      glob:['src/**/*.js', '!src/**/*.spec.js'],
      api: true,
      title: 'API Documentation'
    tutorial: {
      glob: ['content/tutorial/*.ngdoc'],
      title: 'Tutorial'

Serving index.html file

Opening index.html file via file:// protocol will cause a number of troubles. The easier way to avoid it is to run local server. As an options you can use gulp-connect
npm install gulp-connect

gulp.task('connect_ngdocs', function() {
var connect = require('gulp-connect');
    root: 'docs',
    livereload: false,
    fallback: 'docs/index.html',
    port: 8083

Doc comment example

A doc comment looks like this:
 * @ngdoc directive
 * @name rfx.directive:rAutogrow
 * @element textarea
 * @function
 * @description
 * Resize textarea automatically to the size of its text content.
 * **Note:** ie<9 needs polyfill for window.getComputedStyle
 * @example
   <example module="rfx">
     <file name="index.html">
         <textarea ng-model="text"rx-autogrow class="input-block-level"></textarea>
angular.module('rfx', []).directive('rAutogrow', function() {
  //some nice code

Check out the Writing AngularJS documentation wiki article to see what's possible, or take a look at the AngularJS source code for more examples.



Set additional custom JS files are loaded to the app. This allows the live examples to use custom directives, services, etc. The documentation app works with AngularJS 1.2+ and 1.3+. If you include a different version of AngularJS, make sure to include angular-animate.js as well.
Possible values:
- ['path/to/file.js'] file will be copied into the docs, into a js folder - ['', '', '//'] reference remote files (eg from a CDN) - ['../app.js'] reference file relative to the dest folder


default [] Copy additional css files to the documentation app


Optional include Google Analytics in the documentation app.
Example usage:
var opts = {
  analytics: {
    account: 'UA-XXXXXX-YY',
    domainName: ''


Optional include discussions in the documentation app.


default true Show Edit Button for examples.


default "API Documentation" Title to put on the navbar and the page's title attribute.


default '/api' Set first page to open.


default true Whether or not to enable html5Mode in the docs application. If true, then links will be absolute. If false, they will be prefixed by #/.


A URL or relative path to an image file to use in the top navbar.


default no anchor tag is used Wraps the title text in an anchor tag with the provided URL.


default no anchor tag is used Wraps the navbar image in an anchor tag with the provided URL.


default false The best matching page for a search query is highlighted and get selected on return. If this option is set to true the best match is shown below the search field in an dropdown menu. Use this for long lists where the highlight is often not visible.


default null Path to a template of a nav HTML template to include. The css for it should be that of listitems inside a bootstrap navbar:
<header class="header">
  <div class="navbar">
    <ul class="nav">
      {{links to all the docs pages}}
Example: 'templates/my-nav.html'
The template, if specified, is pre-processed using .template.


Use this option to disable any of the four scripts angular, angularAnimate, marked, and prettify (google) which are loaded by default. This would give the user the ability to disable any scripts if they are using methods outside of regular angular/animate loading like browserify.
Example usage:
var opts = {
  loadDefaults: {
    angularAnimate: false

Options for Sections


required glob pattern of files to parse for documentation comments.


default name of the section. Set the title for the section in the documentation app.


default true Set the name for the section in the documentation app.