# LavaCactus
<hr>
#### Workflows
[](https://github.com/quillcraftsman/lavacactus/actions/workflows/testing.yml)
[//]: # ([](https://github.com/quillcraftsman/lavacactus/actions/workflows/lint.yml))
#### Package
[](https://pypi.python.org/pypi/lava-cactus/)
[](https://pypi.python.org/pypi/lava-cactus)
[](https://pypi.python.org/pypi/lava-cactus/)
[](https://github.com/quillcraftsman/lava-cactus/blob/main/LICENSE)
[](https://pypi.python.org/pypi/lava-cactus/)
#### Support
[][documentation_path]
[](https://github.com/quillcraftsman/lavacactus/discussions/)
[](https://github.com/quillcraftsman/lavacactus/issues/)
#### Downloads
[](https://pepy.tech/project/lava-cactus)
[](https://pepy.tech/project/lava-cactus)
[](https://pepy.tech/project/lava-cactus)
[](https://pepy.tech/project/lava-cactus)
#### Languages
[](https://github.com/quillcraftsman/lavacactus/)
[](https://github.com/quillcraftsman/lavacactus/)
#### Development
- [](https://github.com/quillcraftsman/lavacactus/releases)
[](https://github.com/quillcraftsman/lavacactus/)
- [](https://github.com/quillcraftsman/lavacactus/issues/)
[](https://github.com/quillcraftsman/lavacactus/issues/)
- [](https://github.com/quillcraftsman/lavacactus/pulls)
[](https://github.com/quillcraftsman/lavacactus/pulls)
- [](https://github.com/quillcraftsman/lavacactus/discussions/)
#### Repository Stats
[](https://github.com/quillcraftsman/lavacactus)
[](https://github.com/quillcraftsman/django-dry-tests/graphs/lavacactus)
[](https://github.com/quillcraftsman/lavacactus)
* [What is LavaCactus](https://github.com/quillcraftsman/lavacactus#what-is-lavacactus)
* [Examples](https://github.com/quillcraftsman/lavacactus#examples)
* [Super quick tutorial](https://github.com/quillcraftsman/lavacactus#super-quick-tutorial)
* [Contribute](https://github.com/quillcraftsman/lavacactus#contribute)
* [Extended guide](https://github.com/quillcraftsman/lavacactus#extended-guide)
## What is LavaCactus
LavaCactus is the static site generator (SSG) based on [Cactus][cactus_github_page] ported to use with **python 3.12 and django 4**
The original library work with Python 2.6, 2.7, 3.4 and 3.5 and django<2.0
Now it works on **python 3.10-3.12**
## What is Cactus
Cactus is a simple but powerful static website generator using Python and the [Django template system][django_templates].
Cactus also makes it easy to develop locally and deploy your site to S3 directly.
It works great for company, portfolio, personal, support websites and blogs.
## What is new in LavaCactus
* LavaCactus work with python 3.12 (3.10-3.12) and Django 5 (>=2.0)
* LavaCactus can make structure for multilanguage sites
* LavaCactus has GitHub action to publish build on GitHub pages
## Examples
+ https://lavacactus.craftsman.lol - LavaCactus app site and base template example
+ https://craftsman.lol - quill craftsman about website
+ https://findsimilar.org - FindSimilar open source project website (multi-language example)
## Super quick tutorial
Install LavaCactus from pypi
pip install lava-cactus
If you saw no errors, you can now generate a new project
cactus create my-new-project
Where `my-new-project` is the project directory
cd my-new-project
After that you can change your site with django templates. After that just `build` to create static pages
cactus build
To start editing and previewing your site type the following. Then point your browser to localhost:8000 and start editing. Cactus will automatically rebuild your project and refresh your browser on changes.
cactus serve
If you use serve your site will be work on test server and you can use /index.html - links starts with /.
The other way it's to use browser and index.html static file. In this way use index.html in links (without / at the beginning).
## Contribute
You're welcome!
To get started:
* [Developer Guidelines](https://github.com/quillcraftsman/lavacactus/blob/master/CONTRIBUTING.md)
* [Developer Documentation](https://github.com/quillcraftsman/lavacactus/blob/master/DEVELOPER_DOCUMENTATION.md)
## Extended guide
### Creating a new project
You can create a new project by generating a new project structure like this. Make sure the destination folder does not
exist yet.
cactus create [path]
If you did not see any errors, the path you pointed to should now look like this.
- .build Generated site (upload this to your host)
- .github CI/CD github action to publish your site on github pages
- locale Instruction how to use translations if you need
- pages Your actual site pages
- about.html
- contact.html
- error.html A default 404 page
- index.html
- robots.txt
- sitemap.xml
- plugins A list of plugins. To enable remove disabled from the name
- static Directory with static assets
- css
- fonts
- images
- js
- templates Holds your django templates
- base.html
- config.json Configuration file
### Making your site
After generating your site you can start building by adding pages to contents, which can rely on templates. So for
example if you want a page `/articles/2010/my-article.html` you would create the file with directories in your pages
folder. Then you can edit the file and use django's template features.
### Building your site
When you build your site it will generate a static version in the build folder that you can upload to any host.
Basically it will render each page from your pages folder, copy it over to the build folder and add all the static
assets to it so it becomes a self contained website. You can build your site like this:
cd [your-cactus-path]
cactus build
Your rendered website can now be found in the (hidden) [path]/.build folder. Cactus can also run a small webserver to
preview your site and update it when you make any changes. This is really handy when developing to get live visual feedback.
You can run it like this:
cactus serve
### Linking and contexts
Cactus makes it easy to relatively link to pages and static assets inside your project by using the template tags
{% static %} and {% url %}. For example if you are at page `/blog/2011/Jan/my-article.html` and would like to link to
`/contact.html` you would write the following:
<a href="{% url '/contact.html' %}">Contact</a>
Just use the URL you would normally use: don't forget the leading slash.
### Templates
Cactus uses the Django templates. They should be very similar to other templating systems and have some nice
capabilities like inheritance. In a nutshell: a variable looks like this `{{ name }}` and a tag like this
`{% block title %}Welcome{% endblock %}`. You can read the [full documentation][django_templates] at the django site.
### Enabling Plugins
To enable a plugin for your site, change the file name from [PLUGIN].disabled.py to [PLUGIN].py.
### Internationalization
#### Using internationalization with LavaCactus
To enable internationalization for your project:
1. Add a `use_translate` key to your configuration file
2. Add `default_language` key to your configuration file with main language. For example `default_language="en"`
3. Add `other_languages` key to your configuration file with the list of the other languages.
For example `other_languages=["ua", "ru"]`
4. Mark strings for translation in your site (using `{% trans %}`)
5. Put `{% load i18n %}` at the top of template with `trans` tags
6. Run `cactus messages:make`
7. Edit the .po file that was created with translations.
8. Run `cactus build` to create multilanguage site structure
### Extras
Modify `config.json` to set a custom blog path, default author name, or date pattern used to parse metadata. The defaults are:
"blog": {
"path": "blog",
"author": "Unknown",
"date-format": "%d-%m-%Y"
}
#### YAML Variables
By default you can declare variables to be included above each page, for example:
```
test_text: Lorem Ipsum
<p>{{ test_text }}</p>
```
You can declare the variables using YAML instead. Just surround the block with the `---`
and `...` [Document Separators](http://yaml.org/spec/1.1/#id857577). Then the objects
and arrays will be available inside the templates:
```
---
header_text: Lorem Ipsum
custom_object:
name: Lorem
description: Ipsum
custom_array:
-
name: lorem
-
name: ipsum
...
{% for item in custom_array %}
<p>{{ header_text }}: {{ item.name }}</p>
{% endfor %}
<p>{{ custom_object.name }} | {{ custom_object.description }}</p>
```
The *PyYAML* library is used for this functionality.
#### Asset pipeline
Cactus comes with an asset pipeline for your static files. If you'd like to use it, make sure you use the {% static %}
template tag to link to your static assets: they might be renamed in the process.
##### Fingerprinting
Modify `config.json`, and add the extensions you want to be fingerprinting:
"fingerprint": [
"js",
"css"
],
This lets you enable caching with long expiration dates. When a file changes, its name will reflect the change. Great for when you use a CDN.
##### Optimization
Modify `config.json`, and add the extensions you want to be optimizing:
"optimize": [
"js",
"css"
],
By default, Cactus will use:
+ YUI for CSS minification
+ Closure compiler for JS minification (YUI is built-in too, so you can use it!)
Check out `plugins/static_optimizes.py` in your project to understand how this works. It's very easy to add your own
optimizers!
#### Site URL
If you would like for your sitemap to have absolute paths you need to
add a site-url key to your config.json
You can enable this by adding modifying your configuration and adding:
"site-url": "http://yoursite.com",
Note that you need to do this if you want your sitemap to be valid for Google Webmaster Tools.
#### "Pretty" URLs
If you would like to not have ".html" in your URLs, Cactus can rewrite those for you, and make "/my-page.html" look
appear as "/my-page/", by creating the "/my-page/index.html" file.
You can enable this by adding modifying your configuration and adding:
"prettify": true
Note that if you're going to use this, you should definitely set your "Meta canonical" to the URL you're using so as
to not hurt your search rankings:
<link rel="canonical" href="{{ CURRENT_PAGE.absolute_final_url }}" />
#### Extra files
Cactus will auto generate a `robots.txt` and `sitemap.xml` file for you based on your pages.
This will help bots to index your pages for Google and Bing for example.
[cactus_github_page]: https://github.com/eudicots/Cactus
[django_templates]: http://docs.djangoproject.com/en/dev/topics/templates/
[documentation_path]: https://github.com/quillcraftsman/lavacactus
Raw data
{
"_id": null,
"home_page": "https://github.com/quillcraftsman/lavacactus",
"name": "lava-cactus",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "quillcraftsman",
"author_email": "quill@craftsman.lol",
"download_url": "https://files.pythonhosted.org/packages/c7/f4/cdc39dd3ec1baaa5df87e96ecdabd45d17f125f1d6a263dac2bc0a71cc32/lava_cactus-2.0.1.tar.gz",
"platform": null,
"description": "# LavaCactus\n\n<hr>\n\n#### Workflows\n[](https://github.com/quillcraftsman/lavacactus/actions/workflows/testing.yml)\n\n[//]: # ([](https://github.com/quillcraftsman/lavacactus/actions/workflows/lint.yml))\n\n#### Package\n[](https://pypi.python.org/pypi/lava-cactus/)\n[](https://pypi.python.org/pypi/lava-cactus)\n[](https://pypi.python.org/pypi/lava-cactus/)\n[](https://github.com/quillcraftsman/lava-cactus/blob/main/LICENSE)\n[](https://pypi.python.org/pypi/lava-cactus/)\n\n#### Support\n[][documentation_path]\n[](https://github.com/quillcraftsman/lavacactus/discussions/)\n[](https://github.com/quillcraftsman/lavacactus/issues/)\n\n#### Downloads\n[](https://pepy.tech/project/lava-cactus)\n[](https://pepy.tech/project/lava-cactus)\n[](https://pepy.tech/project/lava-cactus)\n[](https://pepy.tech/project/lava-cactus)\n\n#### Languages\n[](https://github.com/quillcraftsman/lavacactus/)\n[](https://github.com/quillcraftsman/lavacactus/)\n\n#### Development\n- [](https://github.com/quillcraftsman/lavacactus/releases)\n[](https://github.com/quillcraftsman/lavacactus/)\n- [](https://github.com/quillcraftsman/lavacactus/issues/)\n[](https://github.com/quillcraftsman/lavacactus/issues/)\n- [](https://github.com/quillcraftsman/lavacactus/pulls)\n[](https://github.com/quillcraftsman/lavacactus/pulls)\n- [](https://github.com/quillcraftsman/lavacactus/discussions/)\n\n#### Repository Stats\n[](https://github.com/quillcraftsman/lavacactus)\n[](https://github.com/quillcraftsman/django-dry-tests/graphs/lavacactus)\n[](https://github.com/quillcraftsman/lavacactus)\n\n* [What is LavaCactus](https://github.com/quillcraftsman/lavacactus#what-is-lavacactus)\n* [Examples](https://github.com/quillcraftsman/lavacactus#examples)\n* [Super quick tutorial](https://github.com/quillcraftsman/lavacactus#super-quick-tutorial)\n* [Contribute](https://github.com/quillcraftsman/lavacactus#contribute)\n* [Extended guide](https://github.com/quillcraftsman/lavacactus#extended-guide)\n\n## What is LavaCactus\n\nLavaCactus is the static site generator (SSG) based on [Cactus][cactus_github_page] ported to use with **python 3.12 and django 4**\n\nThe original library work with Python 2.6, 2.7, 3.4 and 3.5 and django<2.0\n\nNow it works on **python 3.10-3.12**\n\n## What is Cactus\n\nCactus is a simple but powerful static website generator using Python and the [Django template system][django_templates].\nCactus also makes it easy to develop locally and deploy your site to S3 directly.\nIt works great for company, portfolio, personal, support websites and blogs.\n\n## What is new in LavaCactus\n\n* LavaCactus work with python 3.12 (3.10-3.12) and Django 5 (>=2.0) \n* LavaCactus can make structure for multilanguage sites\n* LavaCactus has GitHub action to publish build on GitHub pages\n\n## Examples\n\n + https://lavacactus.craftsman.lol - LavaCactus app site and base template example\n + https://craftsman.lol - quill craftsman about website\n + https://findsimilar.org - FindSimilar open source project website (multi-language example)\n\n## Super quick tutorial\n\nInstall LavaCactus from pypi\n\n pip install lava-cactus\n\nIf you saw no errors, you can now generate a new project\n\n cactus create my-new-project\n\nWhere `my-new-project` is the project directory\n\n cd my-new-project\n\nAfter that you can change your site with django templates. After that just `build` to create static pages\n\n cactus build\n\nTo start editing and previewing your site type the following. Then point your browser to localhost:8000 and start editing. Cactus will automatically rebuild your project and refresh your browser on changes.\n\n cactus serve\n\nIf you use serve your site will be work on test server and you can use /index.html - links starts with /.\nThe other way it's to use browser and index.html static file. In this way use index.html in links (without / at the beginning).\n\n## Contribute\n\nYou're welcome!\n\nTo get started:\n* [Developer Guidelines](https://github.com/quillcraftsman/lavacactus/blob/master/CONTRIBUTING.md)\n* [Developer Documentation](https://github.com/quillcraftsman/lavacactus/blob/master/DEVELOPER_DOCUMENTATION.md)\n\n## Extended guide\n\n### Creating a new project\n\nYou can create a new project by generating a new project structure like this. Make sure the destination folder does not\nexist yet.\n\n cactus create [path]\n\nIf you did not see any errors, the path you pointed to should now look like this.\n\n - .build Generated site (upload this to your host)\n - .github CI/CD github action to publish your site on github pages\n - locale Instruction how to use translations if you need\n - pages Your actual site pages\n - about.html\n - contact.html\n - error.html A default 404 page\n - index.html\n - robots.txt\n - sitemap.xml\n - plugins A list of plugins. To enable remove disabled from the name\n - static Directory with static assets\n - css\n - fonts\n - images\n - js\n - templates Holds your django templates\n - base.html\n - config.json Configuration file\n\n### Making your site\n\nAfter generating your site you can start building by adding pages to contents, which can rely on templates. So for\nexample if you want a page `/articles/2010/my-article.html` you would create the file with directories in your pages\nfolder. Then you can edit the file and use django's template features.\n\n### Building your site\n\nWhen you build your site it will generate a static version in the build folder that you can upload to any host.\nBasically it will render each page from your pages folder, copy it over to the build folder and add all the static\nassets to it so it becomes a self contained website. You can build your site like this:\n\n cd [your-cactus-path]\n cactus build\n\nYour rendered website can now be found in the (hidden) [path]/.build folder. Cactus can also run a small webserver to\npreview your site and update it when you make any changes. This is really handy when developing to get live visual feedback.\n\nYou can run it like this:\n\n cactus serve\n\n### Linking and contexts\n\nCactus makes it easy to relatively link to pages and static assets inside your project by using the template tags\n{% static %} and {% url %}. For example if you are at page `/blog/2011/Jan/my-article.html` and would like to link to\n`/contact.html` you would write the following:\n\n <a href=\"{% url '/contact.html' %}\">Contact</a>\n\nJust use the URL you would normally use: don't forget the leading slash.\n\n### Templates\n\nCactus uses the Django templates. They should be very similar to other templating systems and have some nice\ncapabilities like inheritance. In a nutshell: a variable looks like this `{{ name }}` and a tag like this\n`{% block title %}Welcome{% endblock %}`. You can read the [full documentation][django_templates] at the django site.\n\n### Enabling Plugins\n\nTo enable a plugin for your site, change the file name from [PLUGIN].disabled.py to [PLUGIN].py.\n\n### Internationalization\n\n#### Using internationalization with LavaCactus\n\nTo enable internationalization for your project:\n\n 1. Add a `use_translate` key to your configuration file\n 2. Add `default_language` key to your configuration file with main language. For example `default_language=\"en\"`\n 3. Add `other_languages` key to your configuration file with the list of the other languages. \n For example `other_languages=[\"ua\", \"ru\"]`\n 4. Mark strings for translation in your site (using `{% trans %}`)\n 5. Put `{% load i18n %}` at the top of template with `trans` tags \n 6. Run `cactus messages:make`\n 7. Edit the .po file that was created with translations.\n 8. Run `cactus build` to create multilanguage site structure\n\n### Extras\n\nModify `config.json` to set a custom blog path, default author name, or date pattern used to parse metadata. The defaults are:\n\n \"blog\": {\n \"path\": \"blog\",\n \"author\": \"Unknown\",\n \"date-format\": \"%d-%m-%Y\"\n }\n\n#### YAML Variables\nBy default you can declare variables to be included above each page, for example:\n\n```\ntest_text: Lorem Ipsum\n\n<p>{{ test_text }}</p>\n```\n\nYou can declare the variables using YAML instead. Just surround the block with the `---`\nand `...` [Document Separators](http://yaml.org/spec/1.1/#id857577). Then the objects\nand arrays will be available inside the templates:\n\n```\n---\nheader_text: Lorem Ipsum\ncustom_object:\n name: Lorem\n description: Ipsum\ncustom_array:\n -\n name: lorem\n -\n name: ipsum\n...\n\n{% for item in custom_array %}\n <p>{{ header_text }}: {{ item.name }}</p>\n{% endfor %}\n\n<p>{{ custom_object.name }} | {{ custom_object.description }}</p>\n```\n\nThe *PyYAML* library is used for this functionality.\n\n#### Asset pipeline\n\nCactus comes with an asset pipeline for your static files. If you'd like to use it, make sure you use the {% static %}\ntemplate tag to link to your static assets: they might be renamed in the process.\n\n\n##### Fingerprinting\n\nModify `config.json`, and add the extensions you want to be fingerprinting:\n\n \"fingerprint\": [\n \"js\",\n \"css\"\n ],\n\nThis lets you enable caching with long expiration dates. When a file changes, its name will reflect the change. Great for when you use a CDN.\n\n\n##### Optimization\n\nModify `config.json`, and add the extensions you want to be optimizing:\n\n \"optimize\": [\n \"js\",\n \"css\"\n ],\n\n\nBy default, Cactus will use:\n\n + YUI for CSS minification\n + Closure compiler for JS minification (YUI is built-in too, so you can use it!)\n\nCheck out `plugins/static_optimizes.py` in your project to understand how this works. It's very easy to add your own\noptimizers!\n\n\n#### Site URL\n\nIf you would like for your sitemap to have absolute paths you need to\nadd a site-url key to your config.json\n\nYou can enable this by adding modifying your configuration and adding:\n\n \"site-url\": \"http://yoursite.com\",\n\nNote that you need to do this if you want your sitemap to be valid for Google Webmaster Tools.\n\n\n#### \"Pretty\" URLs\n\nIf you would like to not have \".html\" in your URLs, Cactus can rewrite those for you, and make \"/my-page.html\" look\nappear as \"/my-page/\", by creating the \"/my-page/index.html\" file.\n\nYou can enable this by adding modifying your configuration and adding:\n\n \"prettify\": true\n\nNote that if you're going to use this, you should definitely set your \"Meta canonical\" to the URL you're using so as\nto not hurt your search rankings:\n\n <link rel=\"canonical\" href=\"{{ CURRENT_PAGE.absolute_final_url }}\" />\n\n#### Extra files\n\nCactus will auto generate a `robots.txt` and `sitemap.xml` file for you based on your pages.\n\nThis will help bots to index your pages for Google and Bing for example.\n\n[cactus_github_page]: https://github.com/eudicots/Cactus\n[django_templates]: http://docs.djangoproject.com/en/dev/topics/templates/\n[documentation_path]: https://github.com/quillcraftsman/lavacactus\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Static site generation and deployment.",
"version": "2.0.1",
"project_urls": {
"Changelog": "https://github.com/quillcraftsman/lavacactus/releases",
"Documentation": "https://github.com/quillcraftsman/lavacactus",
"Download": "https://pypi.org/project/lava-cactus/",
"Homepage": "https://github.com/quillcraftsman/lavacactus",
"Release notes": "https://github.com/quillcraftsman/lavacactus/releases",
"Source": "https://github.com/quillcraftsman/lavacactus",
"Tracker": "https://github.com/quillcraftsman/lavacactus/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6914976009f96c7771ce885deb8f149270cc67b9d497a051b20652934d96a13",
"md5": "b96a7e3bc56e1a11181518d87354e7d5",
"sha256": "314a28246a275f16d5f3a7626da0a7987ce95337eeff5690c8c75d3a82bed7ec"
},
"downloads": -1,
"filename": "lava_cactus-2.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b96a7e3bc56e1a11181518d87354e7d5",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 621317,
"upload_time": "2024-10-02T14:32:47",
"upload_time_iso_8601": "2024-10-02T14:32:47.018955Z",
"url": "https://files.pythonhosted.org/packages/e6/91/4976009f96c7771ce885deb8f149270cc67b9d497a051b20652934d96a13/lava_cactus-2.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7f4cdc39dd3ec1baaa5df87e96ecdabd45d17f125f1d6a263dac2bc0a71cc32",
"md5": "0897506296ab6fb6aad2ab44445aab85",
"sha256": "c58123bfad1b2337bd50eac135da85b55e0b671510bb53ecb71646f6acf74e08"
},
"downloads": -1,
"filename": "lava_cactus-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "0897506296ab6fb6aad2ab44445aab85",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 601113,
"upload_time": "2024-10-02T14:32:48",
"upload_time_iso_8601": "2024-10-02T14:32:48.772739Z",
"url": "https://files.pythonhosted.org/packages/c7/f4/cdc39dd3ec1baaa5df87e96ecdabd45d17f125f1d6a263dac2bc0a71cc32/lava_cactus-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 14:32:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quillcraftsman",
"github_project": "lavacactus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"test_requirements": [],
"tox": true,
"lcname": "lava-cactus"
}
JSON
