A (very) basic static site generator in PowerShell
There is a simple example site available here.
Ahab requires PowerShell Core 6.0 minimum.
- Install Powershell Core 6.2.3
- Download
ahab.ps1
Option one:
- Place
ahab.ps1in the root directory of your site - Run from PowerShell with
./ahab.ps1
Option two:
- Place
ahab.ps1in your PowerShell scripts directory (usually/Powershell/scripts) - Configure your PowerShell profile:
# set scripts directory to your scripts folder
$ps_script_dir = "<your path>\Powershell\scripts"
# alias the ahab command
New-Alias ahab $ps_script_dir/ahab.ps1- Run
ahab.ps1from any directory with theahabcommand.
Ahab requires a simple project structure:
- A
contentsdirectory, containing the markdown contents of your site. The structure of the pages and folders incontentswill be the structure of the site. - A
snippetsdirectory, containing any HTML you want to use (for example, afooter.htmlthat you include on every page) - An
assetsdirectory, containing your CSS, JavaScript, image files and other assets. - A
sitedirectory for the build output (Ahab creates this during build)
You can configure the names of these directories in the config.json.
Ahab treats index.md files as the homepage files of their directory. Other files are output as filename\index.html.
Example:
This structure:
Project
|
+-- contents
| |
| +-- index.md
| +-- aFile.md
| +-- myFolder
| |
| +-- index.md
| +-- anotherFile.md
Becomes:
Project
|
+-- site
| |
| +-- index.html
| +-- aFile
| |
| +-- index.html
| +-- myFolder
| |
| +-- index.html
| +-- anotherFile
| |
| +-- index.html
This affects linking between pages. When writing links in your Markdown files, use @BaseURL and the path to the file from the root of your site:
This is my example link to the file named [anotherFile](@BaseURL/myFolder/anotherFile) in the diagram above.
This is my [example link](@BaseURL/myFolder) to the index.md file in myFolder in the diagrame above.
Create a config.json in the root of your project.
Required:
- Provide a base URL. This is the root URL of your site.
Optional:
- Configure the directories for your contents, snippets, assets and output.
- Set default snippets.
Example:
{
"baseURL": "https://example.com",
"contentDir": "src",
"buildDir": "dist",
"assetsDir": "bitsnbobs",
"snippetDir": "partials",
"defaultSnippets": {
"start": "head",
"end": "footer"
}
}If you do not use the optional configuration settings, Ahab uses the following defaults:
{
"contentDir": "contents",
"buildDir": "site",
"assetsDir": "assets",
"snippetDir": "snippets"
}Snippets are pieces of HTML that you can include in your site's pages. There are two ways of including snippets.
Use the defaultSnippets configuration option to include snippets that you want on every page of your site. You can add one to the start of each page, and one to the end.
Example:
Given the following config.json:
{
"defaultSnippets": {
"start": "head",
"end": "footer"
}
}Ahab takes snippets/head.html and adds the contents at the start of every page of your site, then takes snippets/footer.html and adds the contents at the end of every page of your site.
Warning: Ahab does not add any HTML when converting your Markdown to HTML. In other words, without default snippets, your site will have no
<!DOCTYPE>, no<head></head>, and so on. It is strongly recommended to use the default snippets to provide this, at a minimum:
<!-- start snippet, for example head.html -->
<!DOCTYPE html>
<html>
<head>
<title>YOUR SITE TITLE</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<!-- end snippet, for example footer.html -->
</body>
</html>Add the following at any point in your Markdown to include an HTML snippet:
{{ use <snippetName> }}
For example:
{{ use nav }}
Ahab replaces the line with the contents of snippets/nav.html.
Your CSS, JavaScript, images and any other asset files are stored in the assets directory.
To include them in your snippets or Markdown files, use @BaseURL followed by the path to the asset.
For example, adding a CSS link to your head.html snippet:
<!DOCTYPE html>
<html>
<head>
<title>YOUR SITE TITLE</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="@BaseURL/assets/styles.css" />
</head>
<body>