https://github.com/kylecorry31/static-site-generator
A simple static site generator for blog style websites
https://github.com/kylecorry31/static-site-generator
Last synced: about 1 year ago
JSON representation
A simple static site generator for blog style websites
- Host: GitHub
- URL: https://github.com/kylecorry31/static-site-generator
- Owner: kylecorry31
- License: mit
- Created: 2024-05-04T14:05:16.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-04T14:07:29.000Z (about 2 years ago)
- Last Synced: 2025-02-13T10:23:05.738Z (over 1 year ago)
- Language: Python
- Size: 10.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Static Site Generator
A simple static site generator for blog style websites.
## Dependencies
- Python 3
- Install the required packages with `pip install -r requirements.txt`
## Usage
1. Fork this repository
2. Update the content in the `sample` directory to your liking
3. Optionally rename the `sample` directory to something else and update the 'source' entry in `config.yaml`
4. Run `py build.py` to generate the site
5. The generated site will be in the _site directory
Optionally, you can run `py watch.py` run a local server and automatically rebuild the site when changes are made. It will host at http://localhost:8000.
## Configuration
The configuration is stored in `config.yaml`. The following options are available:
- `title`: The title of the site. This can be referenced in templates as `{{ title }}`
- `description`: A description of the site. This can be referenced in templates as `{{ description }}`
- `source`: The directory where the source files are stored. Defaults to `src`
- `destination`: The directory where the generated site will be stored. Defaults to `_site`
- `base_url`: The base URL of the site. This can be referenced in templates as `{{ base_url }}`. All relative URLs will use the base URL as the root.
## Content
### HTML
HTML files are copied to the destination directory, and any mustache tags are replaced with the corresponding values from the configuration file.
### Markdown
Markdown files are converted to HTML and then processed as HTML files.
### Collections
Collections are groups of pages that can be accessed in templates. For example, a collection of blog posts could be accessed in a template as `{{ collections.posts }}`.
To create a collection, just create a new folder in the source directory and add md files to it. The folder name will be the collection name and you can access the collection in templates as `{{ collections. }}`.
You can create an index.html file in the collection directory to create an index page at the root of the collection folder.
You can create an _item.html file in the collection directory to create a template for each item in the collection, otherwise a simple dump of the content is used (or the _default template if provided).
#### Items
The items are markdown files in the collection directory. Each item needs to have a `title` property. Optionally, you can add a `date` property to sort the items by date. The date should be in the format `YYYY-MM-DD`. You can also add a `category` property to categorize the items. See `sample/things` for an example.
Any other properties you add to the item will be available in the template for the item.
#### Properties
The following properties are available on collections:
- `items`: A list of all the items in the collection that you can loop through. Items are sorted by `date` in descending order if the property exists on the item, otherwise, they will be sorted by `title` in ascending order.
- `categories`: If your items contain a `category` property, this will be a list of all the unique categories. Each category contains a `name` and a list of `items` that belong to that category. See `sample/things` for an example.
### Includes
You can create reusable HTML snippets in the `_includes` directory. These can be included in other files using the mustache syntax `{{{ filename-without-extension }}}`.
### Defaults
You can create default layouts for items by creating an `_item.html` file in the `_defaults` directory. This will be used as the template for each item in the collection rather than a simple dump of the content. This can be overridden by creating an `_item.html` file in the collection's directory.
### Example
You can find a live example at https://github.com/kylecorry31/kylecorry31.github.io