DOCSEARCHbyAlgolia
Submit Docs

Ulka Static Site Generator

website·Indexed 29 days ago

https://ulka.js.org/docs/

A fast, pluggable, and lightweight static site generator written in JavaScript. Features include a dedicated template engine (@ulkajs/template-engine), a flexible plugin system, and customizable configuration via ulka-config.js.

Tokens
2.6K
Snippets
20
Records
26
Agent score
60%

What's inside Ulka

  1. Overview of Ulka Static Site Generator

    Ulka is a fast, pluggable, and lightweight static site generator (SSG). Unlike dynamic websites that generate views on demand, Ulka processes data and templates in advance to generate static HTML pages and assets, resulting in faster load times, better scalability, and increased security by removing the need for a database or server-side logic during request handling.

  2. Use JavaScript expressions in Ulka templates

    The @ulkajs/template-engine allows developers to write standard JavaScript directly inside double curly brackets {{}} within template files. For syntax highlighting and formatting in VS Code, use the vscode-ulka extension.

  4. Initialize and build a new Ulka project

    To start a new project with Ulka, use the npm init ulka command to scaffold the project, install dependencies, and then run the build process using the Ulka CLI.
    # Create new project
npm init ulka my-blog

# Goto project directory
cd my-blog

# Install dependencies
npm install 

# Build the site
npx ulka

  5. Install and set up Ulka development environment

    To use Ulka, ensure you have Node.js (LTS version) installed. For the best development experience, use Visual Studio Code with the Ulka extension for syntax highlighting and formatting.

  6. Import partials and modules in Ulka

    You can include other .ulka files using the import() function. This can be done inline for immediate rendering or assigned to a variable to be rendered later in the template. Additionally, standard CommonJS require() is supported for importing JSON files or npm packages.
    <!-- Inline import -->
{{ import("./partials/header.ulka") }}

<!-- Assigned import -->
{{
  const head = import("./partials/header.ulka")
}}
{{ head }}

<!-- Using require for packages or JSON -->
{{ require("./package.json").version }}

{{
  const dayjs = require("dayjs")
  dayjs.format()
}}

  7. Create a new Ulka project

    Initialize a new Ulka project using the npm init ulka command. This generates a basic template and sets up the project structure. After initialization, navigate into the project directory and install the required dependencies.
    npm init ulka <project-name>
cd <project-name>
npm install

  8. Extend Ulka functionality using the plugin system

    Ulka is highly pluggable, allowing developers to transform data at specific points in the build lifecycle. The available plugin hooks are:

    1. afterSetup
    2. beforeBuild
    3. beforeRender $\rightarrow$ afterRender $\rightarrow$ beforeWrite $\rightarrow$ afterWrite
    4. afterBuild

  9. Configure Ulka directory structures and templates

    Ulka offers flexibility in project organization and configuration:

    • Directory Flexibility: Files and layouts can be stored in any directory, provided their locations are defined in the configuration.
    • Frontmatter Configuration: Template-specific configurations can be managed via frontmatter, allowing different settings for individual templates within a collection.
    • Collection Configuration: The global config file can be used to sort collections, change links, or modify layouts for all templates in a collection simultaneously.

  10. Configure and use the Tags Plugin in Ulka

    Add the @ulkajs/plugin-tags plugin to your configuration file. You can optionally specify the matterKey (the key used in front matter for tags) and the contextKey (the key used to store the tags mapping in the template context). Both default to 'tags' if not provided.
    module.exports = {
  plugins: [
    {
      plugin: '@ulkajs/plugin-tags',
      options: {
        matterKey: '_tags', // default => tags
        contextKey: 'tags', // default => tags
      },
    },
  ],
}

  11. Configure content sections in Ulka

    The contents object allows you to define specific rules for different sections of your site (e.g., blog, projects). Each section can specify:

    • match: A glob pattern to match markdown files.
    • layout: The default layout file for that section.
    • ignore: An array of specific files to exclude.
    • link: A function to generate dynamic URLs based on the template's front-matter.
    • forEach: A custom transformation function applied to each template in the section.
    module.exports = {
  contents: {
    blog: {
      match: 'blog/*.md',
      layout: 'blog.ulka',
      link: (template) => `/blog/${template.matter.link}`,
      forEach: (template, index, templates) => {
        // custom transformation logic
      },
    },
    projects: {
      match: 'projects/*.md',
      layout: 'project.ulka',
      ignore: ['projects/secret.md'],
    },
  },
}

  12. Configure Ulka.js special front matter keys

    Ulka.js recognizes specific front matter keys (prefixed with an underscore) to control page behavior. Key options include _layout for specifying the template, _permalink for defining the URL path, and _paginate for generating paginated content based on an array or object.
    ---
_layout: main.ulka
_permalink: _PAGINATE_
_paginate:
  data: tags
  size: 1
  singleValue: true
  permalink: tags/{{ pagination.current; }}/
---