Getting Started

Getting started with Alchemy is designed to be a super-smooth experience. It is worthwhile for you to familiarize yourself with the structure of an alchemy-based website so you aren’t confined by other people’s themes.

Installation

Installing Alchemy is a multi-step (but simple) process. It assumes you have git and npm installed and have created an empty folder you want to be the root of your project.

git clone https://github.com/alchemy-ssg/alchemy.git .

If you want to use a pre-made theme, you need to pick it out and install it. Themes will have installation instructions on their GitHub pages, but our first-party themes are documented here:

If you want to use the Minima theme:

git clone https://github.com/alchemy-ssg/theme-minima.git theme

If you want to use the Docs theme:

git clone https://github.com/alchemy-ssg/theme-docs.git theme

And finally run npm install to download the dependencies:

npm install

Running Alchemy

Alchemy has 2 run commands:

npm run serve watches all the files in the theme/ and posts/ folders and rebuilds anytime one of them is saved:

npm run serve

npm run build only runs the build execution once to avoid accidentally creating an infinite loop if you are editing anything in sensitive folders in a custom build script. Custom build scripts are only run in build mode. They will not be run in watch mode:

npm run build

The file structure

.
├── about.md
├── app.js
├── config.yaml
├── package.json
├── readme.md
├── posts
│   ├── about.md
│   └── theming.md
└── theme
    ├── includes
    │   ├── footer.ejs
    │   ├── head.ejs
    │   └── header.ejs
    ├── layouts
    │   ├── doc.ejs
    │   ├── home.ejs
    │   └── post.ejs
    ├── static
    │   └── logomark.png
    └── styles
        ├── main.css
        └── main.less

• about.md is what will always be printed to about.html, and you should always populate it.
• app.js is the parser script. Feel free to mess with it!
• config.yaml is the configuration file. This is where you will put global variables for the site. Learn more about configuring your website here.
• package.json is a computer-generated file necessary for node.js to execute properly.
• readme.md just the readme file I have written for GitHub. Feel free to delete it or edit it if you wish.
• posts/ the content folder. All content (blog posts, documentation entries, webpages) should go in here.
• theme/ the theme folder. This is where the css, layouts, and visual assets are stored. Read more about the theme folder here.
• theme/static/ the static content folder. This is where you should put your images and videos. Learn more about images and videos in Alchemy here