| Name | kilvin JSON |
| Version |
0.4
JSON |
| download |
| home_page | |
| Summary | A minimal static site generator. |
| upload_time | 2023-06-29 07:58:25 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | |
| keywords |
static site generator
markdow
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# kilvin
Kilvin is a simple static site generator. It takes markdown text and turns it
into a static webpage using layouts. Changes can be made to the page's content,
URLs, and the way the site looks.
- Minimal templating language
- Minimal config with support for custom variables
- Automatic table of contents generation
## Getting Started
### Prerequisites
Kilvin requires the following:
- Python version 3.9 or higher
- pip : package installer
### Instructions
1. Install all prerequisites.
1. Install the `kilvin`.
```console
$ pip install kilvin
```
### Create a site
1. Create a new kilvin site at `./my_project`
```console
$ kilvin init my_project
```
2. Change into your new directory.
```console
$ cd my_project
```
3. Build the site.
```console
$ kilvin build
```
4. Make it available on local server.
```console
$ kilvin server
```
## Command Line
Kilvin has several commands:
```
Usage: kilvin [OPTIONS] COMMAND [ARGS]...
Kilvin is a simple static site generator. It takes markdown text and turns
it into a static webpage using layouts.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
build Build the current project
init Create directory structure for the project
new Create a new markdow post in ./content dir
server Serve the current project
```
Here are some of the most common command:
- `kilvin init PATH`:
- Create a new kilvin site with requisite directory structure.
- `kilvin new PATH`:
- Help create new markdown pages for the project.
- All the new pages are stored in content directory.
- Example:
For `content/about.md`
```console
$ kilvin new about.md
```
For `content/blog/today.md`
```console
$ kilvin new blog/today.md
```
- `kilvin build`:
- Build the site from `./content` files using template in `./layout` and save them `./public` directory.
- All the non-markdown files in `./content` are copied directly without any changes.
- `./static` is also directly copied to `./public`.
- `kilvin server`:
- Serves the site locally.
## Config
Edit `config.toml` for changing the configuration for the project.
### Default Configuration
Basic configuration required for building the site.
```
title = 'My Blog'
url = "https://myblog.xyb"
description = 'My corner of the internet.'
[author]
name = "Kilvin"
email = "kilvin@myblog.xyb"
```
#### Custom Configuration
Custom variables can also be defined in `config.toml`.
```
var1 = 123
[name1]
var2 = "abcxyz"
var3 = 123
```
All the variables in `config.toml` can be accessed in HTML templates with `site` variable.
Example:
- `{{ site.title }}`
- `{{ site.author.name }}`
- `{{ site.name1.var2 }}`
## Pages & Layouts
kilvin organize the rendered site in the same structure that is used to organize the
source conent.
```
└── content
└── about.md
├── posts
| └── _index.md
| ├── firstpost.md
| └── secondpost.md
└── quote
└── _index.md
├── first.md
└── second.md
```
```
└── public
└── about
| └── index.html
├── posts
| └── index.html
| ├── firstpost
| | └── index.html
| └── secondpost
| | └── index.html
└── quote
└── index.html
├── first
└── index.html
└── second
└── index.html
```
### Pages
- All markdown files are referred as a Pages.
### Creating a Page
- To create a page, add a markdown file to `./content` directory.
- Pages can also be organized in sub directories, and all sub directories should have a
`_index.md` page.
- All pages must have a front matter, enclosed in `---` which is used to specify the template or other meta data, along with custom data.
Example:
```markdown
---
template: single.html
title: Why does it have to end?
subtile: A survivor dies.
date: 2022-28-09
---
[TOC]
markdown here
```
- `template`, `tilte`, `subtitle` and `date` are mandatory.
- If `template` field is empty, then default templates are used.
- All the variables can be accessed using `meta` variable in template.
- Example
- `{{ meta.title }}`
- `{{ meta.subtitle }}`
- `{{ meta.date }}`
### Index Page
- All the directories should have `_index.md` page.
- Index Page is special as it has access to variable `pages`.
### Layout
- kilvin uses Jinja2 for templating.
- `./layout` contains the templates for the Pages.
- `./layout` should have `list.html` and `single.html` as the default templates.
#### Variables
All the templates have access to a bunch of variables.
- `site`: date in `config.toml`
- `meta`: data from front matter of the page
- `body`: rendered markdown from the page
- `pages`: (only available to index template) list of all the page in directory
#### Template Usage
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ site.title }}</title>
<link rel="stylesheet" href="/static/style.css">
</head>
<body>
<nav>
<a href="/">Home</a>
<a href="/blog/">Blog</a>
</nav>
<h1>{{ meta.title }}</h1>
<section>
{{ body }}
</section>
</body>
</html>
Raw data
{
"_id": null,
"home_page": "",
"name": "kilvin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "static site generator,markdow",
"author": "",
"author_email": "Pratham Singh <prathms007@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/f8/17541f0f78cc7e81610c1d39bf43c29eb41931a405f6a4cb6cefc6603e75/kilvin-0.4.tar.gz",
"platform": null,
"description": "\n\n\n\n# kilvin\n\nKilvin is a simple static site generator. It takes markdown text and turns it \ninto a static webpage using layouts. Changes can be made to the page's content, \nURLs, and the way the site looks.\n\n- Minimal templating language\n- Minimal config with support for custom variables\n- Automatic table of contents generation\n\n\n## Getting Started\n\n### Prerequisites\n\nKilvin requires the following:\n\n- Python version 3.9 or higher\n- pip : package installer\n\n\n### Instructions\n\n1. Install all prerequisites.\n1. Install the `kilvin`.\n\n```console\n$ pip install kilvin\n```\n### Create a site\n\n1. Create a new kilvin site at `./my_project`\n\n```console\n$ kilvin init my_project\n```\n2. Change into your new directory.\n\n```console\n$ cd my_project\n```\n3. Build the site.\n\n```console\n$ kilvin build\n```\n4. Make it available on local server.\n\n```console\n$ kilvin server\n```\n\n## Command Line\n\nKilvin has several commands:\n\n```\nUsage: kilvin [OPTIONS] COMMAND [ARGS]...\n\n Kilvin is a simple static site generator. It takes markdown text and turns\n it into a static webpage using layouts.\n\nOptions:\n --version Show the version and exit.\n --help Show this message and exit.\n\nCommands:\n build Build the current project\n init Create directory structure for the project\n new Create a new markdow post in ./content dir\n server Serve the current project\n```\n\nHere are some of the most common command:\n\n- `kilvin init PATH`: \n - Create a new kilvin site with requisite directory structure.\n\n- `kilvin new PATH`: \n - Help create new markdown pages for the project.\n - All the new pages are stored in content directory.\n - Example:\n\n For `content/about.md`\n\n ```console\n $ kilvin new about.md\n ```\n\n For `content/blog/today.md`\n\n ```console\n $ kilvin new blog/today.md\n ```\n\n- `kilvin build`:\n - Build the site from `./content` files using template in `./layout` and save them `./public` directory.\n - All the non-markdown files in `./content` are copied directly without any changes.\n - `./static` is also directly copied to `./public`.\n\n- `kilvin server`:\n - Serves the site locally.\n\n\n## Config\n\nEdit `config.toml` for changing the configuration for the project. \n\n### Default Configuration\n\nBasic configuration required for building the site.\n\n```\ntitle = 'My Blog'\nurl = \"https://myblog.xyb\"\ndescription = 'My corner of the internet.'\n\n[author]\nname = \"Kilvin\"\nemail = \"kilvin@myblog.xyb\"\n```\n\n#### Custom Configuration\n\nCustom variables can also be defined in `config.toml`.\n\n```\nvar1 = 123\n\n[name1]\nvar2 = \"abcxyz\"\nvar3 = 123\n```\n\nAll the variables in `config.toml` can be accessed in HTML templates with `site` variable.\nExample:\n\n- `{{ site.title }}`\n- `{{ site.author.name }}`\n- `{{ site.name1.var2 }}`\n\n\n## Pages & Layouts\n\nkilvin organize the rendered site in the same structure that is used to organize the \nsource conent.\n\n```\n\u2514\u2500\u2500 content\n \u2514\u2500\u2500 about.md\n \u251c\u2500\u2500 posts\n | \u2514\u2500\u2500 _index.md\n | \u251c\u2500\u2500 firstpost.md\n | \u2514\u2500\u2500 secondpost.md\n \u2514\u2500\u2500 quote\n \u2514\u2500\u2500 _index.md\n \u251c\u2500\u2500 first.md\n \u2514\u2500\u2500 second.md\n```\n\n```\n\u2514\u2500\u2500 public\n \u2514\u2500\u2500 about\n | \u2514\u2500\u2500 index.html\n \u251c\u2500\u2500 posts\n | \u2514\u2500\u2500 index.html\n | \u251c\u2500\u2500 firstpost\n | | \u2514\u2500\u2500 index.html\n | \u2514\u2500\u2500 secondpost\n | | \u2514\u2500\u2500 index.html\n \u2514\u2500\u2500 quote\n \u2514\u2500\u2500 index.html\n \u251c\u2500\u2500 first\n \u2514\u2500\u2500 index.html\n \u2514\u2500\u2500 second\n \u2514\u2500\u2500 index.html\n```\n\n### Pages\n\n- All markdown files are referred as a Pages.\n\n### Creating a Page\n\n- To create a page, add a markdown file to `./content` directory.\n- Pages can also be organized in sub directories, and all sub directories should have a \n`_index.md` page.\n\n- All pages must have a front matter, enclosed in `---` which is used to specify the template or other meta data, along with custom data.\n\n Example:\n\n ```markdown\n ---\n template: single.html\n title: Why does it have to end?\n subtile: A survivor dies.\n date: 2022-28-09\n ---\n\n [TOC]\n \n\n markdown here\n ```\n\n - `template`, `tilte`, `subtitle` and `date` are mandatory.\n - If `template` field is empty, then default templates are used.\n\n- All the variables can be accessed using `meta` variable in template.\n\n - Example\n\n - `{{ meta.title }}`\n - `{{ meta.subtitle }}`\n - `{{ meta.date }}`\n\n### Index Page\n\n- All the directories should have `_index.md` page.\n- Index Page is special as it has access to variable `pages`.\n\n\n### Layout\n\n- kilvin uses Jinja2 for templating.\n- `./layout` contains the templates for the Pages.\n- `./layout` should have `list.html` and `single.html` as the default templates.\n\n#### Variables\n\nAll the templates have access to a bunch of variables.\n\n- `site`: date in `config.toml`\n- `meta`: data from front matter of the page\n- `body`: rendered markdown from the page\n- `pages`: (only available to index template) list of all the page in directory\n\n#### Template Usage\n\n```\n<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"utf-8\">\n <title>{{ site.title }}</title>\n <link rel=\"stylesheet\" href=\"/static/style.css\">\n </head>\n <body>\n <nav>\n <a href=\"/\">Home</a>\n <a href=\"/blog/\">Blog</a>\n </nav>\n <h1>{{ meta.title }}</h1>\n <section>\n {{ body }}\n </section>\n </body>\n</html>\n",
"bugtrack_url": null,
"license": "",
"summary": "A minimal static site generator.",
"version": "0.4",
"project_urls": {
"Bug Tracker": "https://github.com/shanukun/kilvin/issues",
"Homepage": "https://github.com/shanukun/kilvin"
},
"split_keywords": [
"static site generator",
"markdow"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c686f7b9da5089b6e868c27baadf548e326d9a4c01279f485c3adfe662b9238c",
"md5": "5483f1b245a7f4c58c364d58ed48034e",
"sha256": "4d4e5655c88a76ccf06042d76245cf795a2c53d02b26ae21537c741cfc3a5f94"
},
"downloads": -1,
"filename": "kilvin-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5483f1b245a7f4c58c364d58ed48034e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12729,
"upload_time": "2023-06-29T07:58:23",
"upload_time_iso_8601": "2023-06-29T07:58:23.893448Z",
"url": "https://files.pythonhosted.org/packages/c6/86/f7b9da5089b6e868c27baadf548e326d9a4c01279f485c3adfe662b9238c/kilvin-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f0f817541f0f78cc7e81610c1d39bf43c29eb41931a405f6a4cb6cefc6603e75",
"md5": "76db2f1fd07afa0ee6458224bca3cee8",
"sha256": "54a172f978c0a3cde6e105f9ec653b5c0e427c7404a390aed453db513694bd6d"
},
"downloads": -1,
"filename": "kilvin-0.4.tar.gz",
"has_sig": false,
"md5_digest": "76db2f1fd07afa0ee6458224bca3cee8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12075,
"upload_time": "2023-06-29T07:58:25",
"upload_time_iso_8601": "2023-06-29T07:58:25.946923Z",
"url": "https://files.pythonhosted.org/packages/f0/f8/17541f0f78cc7e81610c1d39bf43c29eb41931a405f6a4cb6cefc6603e75/kilvin-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-29 07:58:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shanukun",
"github_project": "kilvin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "kilvin"
}
