Getting started

Adding Content

This will most likely be where you put the bulk of your efforts when creating any type of documentation site. This section will guide you through some of the many content configurations to get you going.

Basic Content Configuration

Within each section you define you can have one or multiple content sources that Swanky will use to generate a page of documentation.

Example:

sections:
  - title: 'A Brand New Section'
    content: 'path/to/my/content.md' # single content source

Content Sources & Formats

Out of the box Swanky will process HTML and Markdown files without any extra configuration. The location of these sources can be local or external. If the content source is external Swanky will retrieve the content via the URL specified and process - all without breaking a sweat!

Example:

sections:
  - title: 'Some External Content'
    content: 'https://github.com/swanky-docs/guide.swanky-docs.org/blob/master/src/content/getting-started/adding-content.md'

If you have a file format that is not natively supported by Swanky you may need to invoke the awesome power and flexibility of Swanky Processors. A processor is an additional configuration option that tells Swanky how to read and interpret the source. The processor you require might already be available.

As a general guideline the following example illustrates how to configure the Swanky NgDocs Processor to process a JavaScript file containing NGDocs style documentation in the source code:

Example:

sections:
  - title: 'My AngularJS Component'
    content: 'src/content/components/my-component.js'
    preprocessor: # processor configuration
      swanky-processor-ngdocs: {} # additional processor options can be provided here

Content Hierarchy

The Swanky configuration also supports two levels of content hierarchy. This hierarchy can be used to create multi-level navigation within your chosen/custom theme. A 'child' section supports the same configuration options as a top level section.

Example:

sections:
  - title: 'Overview'
    content: 'path/to/overview.md'

    # Sections defined here will have a parent called `Overview`
    subSections:
      - title: 'A Child Section'
        content: 'path/to/child-section.md'

Additional Scripts

Swanky supports the loading of additional scripts that are section specific. These script will only be loaded in the section for which they are specified. The bootstrap option key supports an array of paths to JavaScript files.

Example:

sections:
  - title: 'Foundation'
    content: 'src/content/foundation.md'
    bootstrap:
      - 'path/to/script-1.js'
      - 'path/to/script-2.js'

Supporting live-editing of ngdocs examples

If you use swanky-processor-ngdocs as a preprocessor for ngdoc comments in your source code, you can edit the code for the example components directly in your browser. This is known as live-editing. To enable this feature, one of your additional scripts will need to import swanky-processor-ngdocs/src/bootstrap/angular.bootstrap.js for Angular components, or swanky-processor-ngdocs/src/bootstrap/react.bootstrap.js for React components. Other kinds of components can be supported too.

Angular Example

/* File: path/to/script-1.js */
import ngDocsBootstrap from 'swanky-processor-ngdocs/src/bootstrap/angular.bootstrap';

// This line MUST contain a static-path (rather than a variable) so that Webpack can determine the list of files to require() at compile-time.
const modulesToRequire = require.context('../../content/angular-components/', true, /^.*\/index.js$/);

// Load all of the Angular modules that you can find then boot the app.
function requireAll(requireContext) {
  return requireContext.keys().map(requireContext);
}

const modules = requireAll(modulesToRequire);

// Assume module.default is the module name (a string)
const moduleMap = modules.reduce((acc, mod) => Object.assign(acc, {[mod.default]: mod}), {});

ngDocsBootstrap(moduleMap);

React Example

/* File: path/to/script-1.js */
import reactBootstrap from 'swanky-processor-ngdocs/src/bootstrap/react.bootstrap';

// This line MUST contain a static-path (rather than a variable) so that Webpack can determine the list of files to require() at compile-time.
const modulesToRequire = require.context('../../content/react-components/', true, /^.*\/index.jsx$/);

// Load all of the React modules that you can find.
function requireAll(requireContext) {
  return requireContext.keys().map(requireContext);
}

// Pass an object-map of moduleNames-to-module-functions: {'DatePicker': function DatePicker() ..., CardInput: function CardInput
let moduleMap = {};

requireAll(modulesToRequire).forEach(module => {
  let moduleKeys = Object.keys(module.default);
  moduleKeys.forEach(moduleKey => moduleMap[moduleKey] = module.default[moduleKey]);
});

reactBootstrap(moduleMap);

Advanced Content Configuration

Using the concepts outlined in the Basic Content Configuration section we can start to combine all the available configuration options into complex page structures.

To illustrate a 'real world' use case you may have a section of your documentation that has one or more sections that are driven from Markdown__ files e.g. Overview, Accessibility Guidelines and another section that is driven by JSDoc style comments in the source code of the documented library e.g API specification, Working Example etc. Expecting a whole development team to use __one method of documentation is not realistic. Swanky Docs will enable you to capture all these various documentation sources to construct a seamless page that caters to all styles of the documentation capturing process.

Example:

sections:
  - title: 'A Complex Section'
    bootstrap:
      - 'path/to/script.js'
    content: # Array of content sources that will be combined and processed into one page

      # External Content Source
      - title: 'Overview'
        src: 'https://some-external-url/content.md'

      # Markdown
      - title: 'Markdown Content'
        src: 'path/to/some/content.md'

      # JS Docs
      - title: 'Source Code Content'
        src: 'src/content/components/my-component.js'
        preprocessor:
          swanky-processor-ngdocs: {}