vite-plugin-dedale v0.0.16
Vite Plugin Dedale
Table of Content
- Introduction
- Getting Started
- Configuration
- Load Files
- Utility Functions and variables for Use in Templates
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 :
- 11ty
- Astro
- Vite-plugin-eleventy (whose code inspired the development of vite-plugin-dedale)
- Vituum
- Vite-plugin-ssr.
Getting Started
Install vite-plugin-dedale in your Vite project
$ npm install --save-dev vite-plugin-dedaleCreate a
vite.config.tsfile 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", }, }, ], }), ], });"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>- Run the development server:
npm run dev - 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(requirednunjucks|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>
@endroute
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>
@endifdevmode
Returns a boolean indicating whether the project is running in development mode.
Returns
trueif the project is running in development mode,falseotherwise.
Examples
nunjucks :
{% if devmode %}
<!-- some development-specific content -->
{% endif %}edge-js
@if(devmode)
<!-- some development-specific content -->
@endifbase
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>