Skip to content

Latest commit

 

History

History
142 lines (105 loc) · 5.83 KB

CONFIGURING.md

File metadata and controls

142 lines (105 loc) · 5.83 KB
Raw

Configuring Spoonfeed

The config file is spoonfeed.config.js and must exports a valid config object, or else the compilation will fail. If missing, default config will apply.

Config files should look like this (note that this is an example and none of the fields shown are required):

module.exports = {
  documents: {
    source: 'filesystem',
    path: 'docs'
  },
  build: {
    target: 'build'
  }
}

Note: Paths are relative to the config file.

Configuring documents source

Documents can be part of a category, although Spoonfeed doesn't support subcategories. Document without categories will always be shown at the top of the list.

No matter the source you're pulling from, documents name and slug will be determined by the first Heading 1 encountered.

  • documents.source - string (default: 'filesystem')
    The document source to use. Spoonfeed supports two document sources: filesystem and registry.

  • documents.assets - string (default: 'assets')
    Folder where documents are located, relative to the config file.

  • documents.path - string (default: 'docs')
    Folder where documents are located, relative to the config file.

Filesystem document source settings

This is the default document source used by Spoonfeed. The specified folder will be scanned and the documentation tree will be built from this. You can force file sorting by prepending [int]- to the filename.

By default, categories name and slug are determined based on the folder name. If you want to use a different name, you can do so by adding a manifest.json file in the folder. It can also contain additional data that'll be passed to the Preact component rendering time. Slug cannot be set.

Example manifest
{ "name": "My Awesome Category" }

Registry document source settings

  • documents.documents - array
    List of documents and categories

Basic UI settings

  • ui.title - string (default: 'Documentation')
    Title of your documentation. Will be shown in tab title and used in SEO tags.

  • ui.description - string (default: 'A documentation generated by Spoonfeed')
    Description of your documentation. Will be used in SEO tags.

  • ui.copyright - string? (default: null)
    Defines the copyright notice shown on the web page. null means no copyright notice. To get the current year, you can put {{ year }}.
    - Example: © {{ year }} Borkenware

  • ui.logo - string? (default: null)
    Logo shown at the top of the documentation. If null, the title will be shown in plaintext.

  • ui.favicon - string? (default: null)
    Icon shown in browser's tabs. We recommend a 128x128 PNG file, since this will be used in SEO tags. An ICO file will be generated for the actual favicon.

  • ui.acknowledgements - boolean (default: true)
    Whether the "Acknowledgements" page listing dependencies and their license should be generated. This feature ensure compliance regarding third party software licenses and the preservation of copyright notices.

Build options

  • build.target - string (default: 'build')
    Where built assets will be saved.

  • build.mode - string (default: 'preact')
    What the final result should compile to. Possible values are:

    • preact (Default)
    • html (Not implemented)

  • build.sourcemaps - boolean (default: true)
    Whether source maps should be generated or not.

  • build.optimizeImg - boolean (default: true)
    Whether images should be optimized or not.

  • build.offline - boolean (default: true)
    Whether Spoonfeed should generate the necessary service worker and manifest to make the webpage available to users even if they go offline (provided they visited the docs at least once prior) or not.

  • build.mangle - boolean (default: true)
    Whether exports should be mangled or not. Only applicable for preact builds.

  • build.split - boolean (default: true)
    Whether Spoonfeed should make use of code splitting or not. Reduces the initial bundle size. Only applicable for preact builds.

  • build.devtools - boolean (default: true)
    Whether Spoonfeed should include Preact devtools or not. Disabling it will result in a smaller bundle.

Pre-rendering server-side options

Note: Those will only be used if you set your app to compile to a Preact app.

  • ssr.generate - boolean (default: false)
    Whether Spoonfeed should generate a web server for pre-rendering the Preact app.

  • ssr.http2 - boolean (default: false)
    Whether the HTTP server should be a HTTP/2 server. Requires a valid SSL certificate.
    Note: When enabled, browsers not supporting HTTP/2 will be unable to connect.

  • ssr.redirectInsecure - boolean (default: false)
    Redirects plain HTTP requests to HTTPS. Requires a valid SSL certificate.

  • ssr.ssl.key - string
    Path to the SSL private key. It'll be copied in the build target folder.

  • ssr.ssl.cert - string
    Path to the SSL certificate. It'll be copied in the build target folder.

Why generate a server?

Although Preact apps are fantastic, they absolutely require the target device to run JS code to function. While this isn't much of a problem nowadays, it still means it'll take longer for the first contents to be displayed to the end user. This gives a feeling of the app taking forever to load, and it affects your SEO score (and even worse, not all search engines run JS code when crawling).

To remedy those issues while keeping the advantages of client-side-rendering, you can give the user a pre-rendered version of your website, which means content will be instantly available, and then hydrate the page to bind events and start using client-side-rendering from this point on. It also means your webpage doesn't require JavaScript to be usable.

Basic theme configuration

  • theme.theme - TBD
  • theme.colors - TBD

Advanced theme & UI configuration

TBD