index : livejrnl.git

c960d38a0f89468d5b5aeafbf6f5a0f0ef66c846 [patch]

86d73a8805b1240f801b59ecd6a0330b3054f864

26c16f7408a388f0c0b00d7c5dbffdb8b658abf1

c960d38a0f89468d5b5aeafbf6f5a0f0ef66c846.tar.gz

docs: add README

Diff

 README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d1a60ac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
# LiveJrnl

Render a [**jrnl.sh**](https://jrnl.sh) journal as a static site. LiveJrnl uses [Jinja](https://github.com/pallets/jinja) for templating. Inspired by [jrnl-render](https://github.com/sloria/jrnl-render).

Why the name LiveJrnl? I was feeling nostalgic for LiveJournal circa 2004 and wanted to recreate that experience. I've used `jrnl` for a few years now and simply love the simplicity of it. I also like puns and wordplay.

## Disclaimer
Using this project kinda emulates the open source experience of 2004. Its gonna be clunky to use on its own. The good thing is, it mostly follows the [Unix philosophy](https://en.wikipedia.org/wiki/Unix_philosophy) by only doing one thing - generate files based on the json output from `jrnl`. If you use a build script, you're gonna have a good time.

There's also no real error checking. Make sure all of your paths are writeable, your journal is accessible and populated, and don't be an idiot running this as root.

## Install

* Clone the repository and open the folder
* Create a virtual environment `virtualenv -p python3 env`
* Activate `source env/bin/activate`
* Install requirements `pip install -r requirements.txt`
* Deactivate `deactivate`

## Usage
* Navigate to the install folder
* Activate the virtual environment `source env/bin/activate`
* Read the help `python livejrnl.py --help`
* When done, `deactivate`

To view my personal build script that builds the site, RSS feed, and CSS, you can look at the [livejrnl-builder](https://codeberg.org/berrysweet/livejrnl-builder) repo.

## Templates

The following files **must** be present in the template directory:

| Input File            | Output File  |
| --------------------- | ------------ |
| `index.html.template` | `index.html` |
| `feed.xml.template`   | `feed.xml`   |

All features of [Jinja](https://github.com/pallets/jinja) are available with no restrictions, even extensions!


### Template Variables

The template variables LiveJrnl uses are:

| Variable        | Type  | Description         |
| --------------- | ----- | ------------------- |
| `{{ entries }}` | Array | The list of entries |

The template variables for individual entries are:

| Variable            | Type   | Description                 |
| ------------------- | ------ | --------------------------- |
| `{{ entry.title }}` | String | The title of the entry      |
| `{{ entry.date }}`  | String | The date stamp of the entry |
| `{{ entry.time }}`  | String | The time stamp of the entry |
| `{{ entry.body }}`  | String | The contents of the entry   |

These also work for the RSS template.

## Example

Print a list of entries and their contents, beginning with the newest:

```
{% for entry in entries|reverse %}
	<p>{{ entry.title }}</p>
	<p>{{ entry.date }} at {{ entry.time }}</p>
	<p>{{ entry.body }}</p>
	</br>
{% endfor %}
```

## Known Issues

If you have a large journal with a resource heavy template, you're gonna have a bad time. This outputs **every entry on a single page** because I didn't bother to implement pagination *at all*.

Pagination is not a priority because this whole thing is mostly for me, and I personally plan to "archive" my journal every year by copying the output files to their own year folder, so the number of entries *shouldn't* reach a point where performance and file size is an issue.

## License

- TBA