Skip to content

Latest commit

 

History

History
326 lines (235 loc) · 9.55 KB

README.md

File metadata and controls

326 lines (235 loc) · 9.55 KB
Raw

Vite Plugin Dedale

Table of Content

Introduction

vite-plugin-dedale is a plugin for Vite that helps you navigate the complexities of creating static sites, much like the mythological figure Daedalus (or "Dédale" in French).

vite-plugin-dedale offers a simple and flexible solution for managing the routes and templates of your static site. You can use JavaScript or TypeScript for your routes, and Nunjucks or Edge-js for your templates. vite-plugin-dedale also allows you to read Markdown files and retrieve their content and metadata.

When to use vite-plugin-dedale:

  • If you need to generate a static site from variable data, such as a brochure website, a portfolio, a blog, or a documentation site

  • If you want to use Nunjucks or Edge-js as your template engine and JavaScript or TypeScript for your routes

If vite-plugin-dedale doesn't meet your needs, you may want to consider other tools and plugins such as :

Getting Started

  1. Install vite-plugin-dedale in your Vite project

    $ npm install --save-dev vite-plugin-dedale

  2. Create a vite.config.ts file at the root of your project and add the following configuration:

    import { defineConfig } from "vite";
import { dedale } from "vite-plugin-dedale";

export default defineConfig({
  plugins: [
    dedale({
      templateDir: "templates",
      templateEngine: "nunjucks",
      routes: [
        {
          url: "/",
          template: "index.njk",
          data: {
            title: "Home",
          },
        },
        {
          url: "/about/",
          template: "index.njk",
          data: {
            title: "About Us",
            foo: "bar",
          },
        },
      ],
    }),
  ],
});

  3. "Create a 'templates' directory at the root of your project and add a Nunjucks template file called 'index.njk' with the following content:"

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>{{ title }}</title>
  </head>
  <body>
    <h1>{{ title }}</h1>
    <p>Welcome to my site!</p>
    {% if foo %}
    <span>{{ foo }}</span>
    {% endif %}
   <div id="app"></div>
	  <script type="module" src="/src/main.ts"></script>
  </body>
</html>

  4. Run the development server:

    npm run dev

  5. Visit http://localhost:5173/ or http://localhost:5173/about/ in your browser to see your static site in action.

For a more complete example, check out the Daedalus blog, which uses vite-plugin-dedale : https://github.com/achtaitaipai/daedalus-s-blog

Configuration

vite-plugin-dedale accepts the following options in its configuration:

  • templateDir (required): The path to the directory containing your templates.
  • contentDir (optional): The path to the directory containing your content files (such as Markdown files). This option enables hot reloading of these files in development mode.
  • templateEngine (required nunjucks | edge) defines the template engine to use for rendering routes.
  • configureTemplateEngine (optional): A function that allows you to customize the template Engine environment . This function takes in a Nunjucks or Edgejs environment as an argument and returns a modified version of that environment. For more information on how to configure Nunjucks, refer to the Nunjucks documentation or the Edge-js documentation.
  • routes (required): An array of route objects, each with the following properties:
    • url (string): The URL for this route.
    • template (string): The name of the template to use for this route.
    • data (object, optional): An object containing data to be passed to the template for this route.

Load Files

vite-plugin-dedale provides several utility functions for parsing and loading Markdown files:

loadMdFile

Loads the content and frontmatter metadata from a single Markdown file.

import { loadMdFile } from "vite-plugin-dedale";

type Fontmatter = {
  title: string;
};

const aboutContent = loadMdFile<Frontmatter>("/content/page/about.md");

console.log(aboutContent.frontmatter.title); // "About us"
console.log(aboutContent.content); // "<p>...</p>"

Parameters

  • filePath (string): The file path of the Markdown file.

Returns

An object with the following properties:

  • filepath (string): The file path of the Markdown file.
  • filename (string): The file name of the Markdown file.
  • frontmatter (T): The frontmatter metadata of the file.
  • raw (string): The content of the file.
  • content (string): The parsed content of the file.
  • headings (array): A list of headings (h1 -> h6) in the Markdown. This list follows the type: { depth: number; slug: string; text: string }[].

loadMdFiles

Loads the content and frontmatter metadata from all Markdown files in the first level of the specified directory.

import { loadAllMdFilesFrom } from "vite-plugin-dedale";

type ArticleFrontmatter = {
  title: string;
  date: string;
};

const articles = loadAllMdFilesFrom<ArticleFrontmatter>("/content/articles");

console.log(articles[0].frontmatter.title); // "My Blog Post"
console.log(articles[0].content); // "<p>This is the content of my blog post.</p>"

Parameters

  • filePath (string): The file path of the Markdown file.

Returns

An array of objects, each with the following properties:

  • filepath (string): The file path of the Markdown file.
  • filename (string): The file name of the Markdown file.
  • frontmatter (T): The frontmatter metadata of the file.
  • raw (string): The content of the file.
  • content (string): The parsed content of the file.
  • headings (array): A list of headings (h1 -> h6) in the Markdown. This list follows the type: { depth: number; slug: string; text: string }[].

Utility Functions and variables for Use in Templates

vite-plugin-dedale provides two utility functions and variables that can be used in Nunjucks or Edge-js templates:

routes

Returns an array of all routes that match the provided pattern.

Parameters

  • pattern (string): A pattern that uses glob syntax to match the routes.

Returns

An array of objects, each representing a route with the following properties:

  • url (string): The URL of the route.
  • template (string): The path to the template file.
  • data (object): An optional data object that will be passed to the template when rendering the route.

Examples

nunjucks :

{% for route in routes('/blog/*') %}
	<a href="{{ route.url }}">{{ route.data.title }}</a>
{% endfor %}

edge-js :

@each(route in routes('/blog/*'))
	<a href="{{ route.url }}">{{ route.data.title }}</a>
@end

route

Returns the first route that matches the provided pattern.

Parameters

  • pattern (string): A pattern that uses glob syntax to match the route.

Returns

An object representing the route with the following properties:

  • url (string): The URL of the route.
  • template (string): The path to the template file.
  • data (object): An optional data object that will be passed to the template when rendering the route.

Examples

nunjucks :

{% set aboutRoute = route('/about/') %}
{% if aboutRoute %}
	<a href="{{ aboutRoute.url }}">About</a>
{% endif %}

edge-js :

@set('aboutRoute',route('/about/'))
@if(aboutRoute)
	<a href="{{ aboutRoute.url }}">About</a>
@endif

devmode

Returns a boolean indicating whether the project is running in development mode.

Returns

  • true if the project is running in development mode, false otherwise.

Examples

nunjucks :

{% if devmode %}
	<!-- some development-specific content -->
{% endif %}

edge-js

@if(devmode)
	<!-- some development-specific content -->
@endif

base

Returns the base URL defined in the Vite configuration.

Returns

  • A string representing the base URL defined in the Vite configuration.

Examples

nunjucks :

<a href="{{ base }}/about/">About</a>

edge-js

<a href="{{ base }}/about/">About</a>