Staticus Website Compiler - Comprehensive Project Configuration

This document provides a complete reference to all configuration variables used in the Staticus Website Compiler, accurately reflecting the definitions from config.json and their implementations in Staticus. All options, including advanced configurations such as the { "toplevel": true } setting for mangle, are now fully detailed.

Required Settings

require.site.url

• Type: string
• Example:

  "require": {
    "site": {
      "url": "https://www.staticuswebsitecompiler.com"
    }
  }
  

• Description: Defines the base URL of the website. It is essential for setting og:url meta tags and generating the sitemap.
• Parameters:
  • Must be a valid URL.
• Usage in Code:
  • Referenced for og:url generation.
  • Used in sitemap creation to establish accurate links.

Optional Settings

Brand Settings (option.brand)

Controls branding elements such as icons, backgrounds, and alignment for visual consistency.

option.brand.adjust

• Description: Configures how foreground and background images are processed, including alignment, blur, and visual effects.
• Usage in Code:
  • Utilized for image composition and favicon generation.

Foreground

"foreground": {
  "alignment": { "x": "center", "y": "center" },
  "blur": 0,
  "modulate": {}
}

• Parameters:
  • alignment: X and Y values (left, center, right, top, bottom).
  • blur: Integer specifying blur intensity.
  • modulate: Object for additional visual effects.

Background

"background": {
  "alignment": { "x": "center", "y": "center" },
  "apply": { "square": true, "wide": true },
  "blur": 0,
  "modulate": {}
}

• Parameters:
  • apply.square: Boolean; applies settings to square images.
  • apply.wide: Boolean; applies settings to wide images.
  • blur: Integer for blur effect.
  • modulate: Object for color modulation.

option.brand.size

• Description: Specifies the sizes for various branding images including favicons and touch icons.

• Usage in Code:

  • Processed for favicon and touch icon generation.

• ICO Sizes:

  "ico": [16, 32, 48, 64, 96, 128]
  

• Image Sizes:

  "image": {
    "apple-touch-icon-57x57.png": { "width": 57, "height": 57 },
    "apple-touch-icon-120x120.png": { "width": 120, "height": 120 },
    "mstile-310x310.png": { "width": 310, "height": 310 },
    "favicon-512.png": { "width": 512, "height": 512 }
  }
  

Syntax Highlight Settings (option.highlight.syntax)

• Description: Controls the generation and management of syntax-highlighted code blocks using PrismJS. This includes the selection of languages, plugins, themes, and autoloading behaviors.

• Usage in Code:

  • Used during Gulp tasks to copy and organize PrismJS components.
  • Generates prism.js and prism.scss index files with import and @forward statements.
  • Dynamically configures Prism Autoloader if enabled.

option.highlight.syntax

path

Output will be placed into a prism/ subfolder inside the specified directories.

Note: All output files will be placed into a prism/ subfolder inside the specified css and js output paths. This ensures a consistent structure for all themes, plugins, and language modules.

Example

"path": {
  "css": "css/module",
  "js": "js/module"
}

Of course! Here's the correctly formatted Markdown version:

Example Output Files

If path.css is set to "css/module", the generated files will be placed under:

css/module/prism/_theme/prism.css
css/module/prism/_plugin/prism-autolinker.css
css/module/prism/prism.scss

And similarly for JavaScript, if path.js is set to "js/module", the generated files will be placed under:

js/module/prism/_plugin/prism-autolinker.js
js/module/prism/_language/prism-html.js
js/module/prism/prism.js

theme

Example

"theme": {
  "enabled": true,
  "include": [
    "prism",
    "prism-okaidia"
  ]
}

language

Example

"language": {
  "enabled": true,
  "include": [
    "html",
    "css",
    "javascript"
  ]
}

plugin

Example

"plugin": {
  "enabled": true,
  "include": [
    "autolinker",
    "toolbar",
    "copy-to-clipboard",
    "line-numbers"
  ]
}

Autoloader Plugin Special Behavior

If the autoloader plugin is listed under plugin.include, additional autoload functionality is configured:

• Language Autoloading: When the autoloader plugin is active, individual languages are not manually imported. Instead, the Prism Autoloader dynamically loads languages at runtime when needed.

• Autoloader Configuration in Output: The generated prism.js will automatically append:

  if (Prism.plugins.autoloader) {
    Prism.plugins.autoloader.languages_path = '/asset/js/module/prism/language/';
  }
  

  This tells PrismJS where to find language components for dynamic loading.

• Without Autoloader: If the autoloader is not included, languages listed in language.include are manually imported and bundled into the prism.js output.

Example Full Configuration

"highlight": {
  "syntax": {
    "enabled": true,
    "generateImports": true,
    "path": {
      "css": "css/module/prism",
      "js": "js/module/prism"
    },
    "theme": {
      "enabled": true,
      "include": [
        "prism"
      ]
    },
    "language": {
      "enabled": true,
      "include": [
        "html",
        "css",
        "javascript"
      ]
    },
    "plugin": {
      "enabled": true,
      "include": [
        "autolinker",
        "copy-to-clipboard",
        "data-uri-highlight",
        "inline-color",
        "line-numbers",
        "match-braces",
        "show-language"
      ]
    }
  }
}

Notes

• Autoloader and Languages: When autoloader is active, no manual language imports are generated, all languages supported are included as individual files.
• Theme Customization: Any valid PrismJS CSS theme name can be included.
• Plugin Support: Plugin JavaScript and CSS files are copied and included based on the selected plugins.
• Import/Forward: The generateImports option ensures an automatically updated prism.js and prism.scss are generated based on actual included components.

Image Settings (option.image)

• Description: Controls advanced watermarking features applied to images during processing.

• Usage in Code:

  • Used during image processing for adding watermark layers dynamically based on file matching patterns.

option.image.watermark

• Type: array

• Description: Defines a list of watermark rules. Each rule specifies:

  • pattern: Files the watermark should apply to.
  • layers: One or more watermark layers to apply.

Each Watermark Rule

Watermark Layer (layers entries)

Each layer defines how a specific watermark image is applied.

Resize Options

The resize field controls how the watermark image is scaled before being applied.

It can be specified as:

Advanced Resize (object)

Additional Notes on Resize Behavior

• Aspect Ratio: Resize always preserves the watermark’s original aspect ratio unless GraphicsMagick options override it.

• No Upscaling: If the computed size would upscale the watermark beyond its original size, it will not be enlarged unless you override this using GM options.

• Smart Percentage Targets:

  • %t → Target image dimension (background image).
  • %w → Original watermark image dimension.

• Pixels (px): Provide a fixed pixel dimension (e.g., "512px") to set an exact width or height.

Related GraphicsMagick Resize Options

You can use GM syntax to further control behavior:

Example: If you wanted to force exact size (even if it distorts):

"gmOptions": "-resize 256x256!"

Example (Mixed Resize Strategies)

"resize": {
  "width": "50%t",
  "minWidth": "256px",
  "maxWidth": "100%t",
  "maxHeight": "10%t"
}

This configuration:

• Attempts to make watermark 50% of target width.
• Ensures at least 256px width.
• Ensures width never exceeds 100% of target width.
• Ensures height never exceeds 10% of target height.

Example

"image": {
  "watermark": [
    {
      "pattern": "**/*.watermark_tile.*",
      "layers": [
        {
          "image": "brand/_watermark_tile.png",
          "gravity": "Center",
          "dissolve": 37.5,
          "resize": "100%",
          "background": "none",
          "gmOptions": "-tile"
        }
      ]
    },
    {
      "pattern": "**/*.watermark_logo.*",
      "layers": [
        {
          "image": "brand/_watermark_tile.png",
          "gravity": "Center",
          "dissolve": 37.5,
          "resize": "100%",
          "background": "none",
          "gmOptions": "-tile"
        },
        {
          "image": "brand/_watermark_logo.png",
          "gravity": "SouthEast",
          "dissolve": 100,
          "resize": {
            "width": "50%t",
            "minWidth": "256px",
            "maxWidth": "100%t",
            "maxHeight": "10%t"
          },
          "background": "none"
        }
      ]
    }
  ]
}

Notes

• Multiple Layers: Layers are applied in the order listed — first layer applied first, second on top, etc.

• Gravity: Determines positioning. Center is commonly used; SouthEast places watermark at bottom-right.

• Resize %t vs %w:

  • %t: Resizes based on target (background) image dimensions.
  • %w: Resizes based on the original watermark image dimensions.

• Background: "none" ensures transparency behind the watermark; other colors are supported.

• GraphicsMagick Options: Add custom behavior — e.g., tiling, blending modes.

Minification Settings (option.minify.js)

• Description: Defines JavaScript minification options to reduce file size.

• Usage in Code:

  • Applied during JS processing.

• Parameters:

  • keep_classnames: If true, retains class names.
  • keep_fnames: If true, retains function names.
  • compress: Enables JS compression.
  • mangle: Controls mangling of names.
    • Boolean: true for full mangling, false to disable.
    • Object:

      { "toplevel": true }
      

      Enables mangling of top-level variable and function names.

  "minify": {
    "js": {
      "keep_classnames": false,
      "keep_fnames": false,
      "compress": true,
      "mangle": { "toplevel": true }
    }
  }
  

Path Settings (option.path)

• Description: Manages file and directory handling during compilation.

• Usage in Code:

  • Used to filter paths during processing.

• Ignore Navigation:

  "ignore_nav": ["index", "404"]
  

• Ignore Prefix:

  "ignore_prefix": "_"
  

• Ignore Package:

  "ignore_package": ["example"]
  

• Ignore Sitemap:

  "ignore_sitemap": ["404", "503"]
  

URL Configuration (option.url.html_extension)

• Description: Specifies whether URLs should include .html extensions.

• Usage in Code:

  • Applied during watch process.

  "html_extension": true
  

File Watching Settings (option.watch)

• Description: Defines file watching behaviors for live reloading.

• Usage in Code:

  • Used with BrowserSync.

• Delay Browser:

  "delay_browser": 1250
  

• Delay Change:

  "delay_change": 750
  

Note: All configurations presented here now include advanced settings such as { "toplevel": true } for mangle, ensuring no options have been omitted and maintaining consistency across all related files for proper functionality within the Staticus Website Compiler project.