Skip to content

Home

Jump to bottom
Kimon Karathanasopoulos edited this page Mar 5, 2018 · 3 revisions

a zenbu

Welcome to the tilde-zenbu wiki!

This serves as a general resource and set of guidelines for understanding what the project does and how to use it yourself!

Table of Contents

Introduction

One look is something something thousand words, so here's what the project does:

testfile.txt, the file sent to the package

A Nice Post

Hello! I'm some <b>bold</b> text!

<q>This is a <i>lean</i>quote, I think.</q>

<h> Chapter 2
<img> myimage.png center "a lovely display" "secret text!"
This is some text that I'd like to accompany my image...

...but this text is in a whole different &lt;p&gt;lanet!

<add> pssst, don't forget about this tidbit

The formatted html file produced by the package:

<div>
<a name="testfile" href="#testfile" title="testfile"><time class="posttime" datetime="2018-03-05 02:27">Mar 5 2018</time></a>
<h2>A Nice Post</h2>
<p>Hello! I'm some <strong>bold</strong> text!
</p>
<p><blockquote>This is a <em>lean</em>quote, I think.</blockquote>
</p>
<h3>Chapter 2</h3>
<p><div class="c"><img src="zenbu/image/myimage.png" alt="a lovely display" title="secret text!"></div>
This is some text that I'd like to accompany my image...
</p>
<p>...but this text is in a whole different &lt;p&gt;lanet!
</p>
<p class="addendum"> pssst, don't forget about this tidbit
</p>
</div>

Those are the basics. After that, the new post is logged and an index.html is produced from all logged posts and sent to tilde.town.

Formatting

Some basic rules about the text file you provide to the package:

  • The filename (sans the extension) is the name of the post. It should only contain regular alphanumeric characters and hyphens.
  • The first line of the file is the title.
  • Each "paragraph" is separated by an empty line, since:
    • Every non-special line (see below) causes a new <p> to open.
    • Every empty (newline-only) line closes the </p>.
  • Regular html tags can be inserted within text, as some tags such as <a> and <ul> haven't been implemented yet.
  • However, this also means that the characters <, >, and & will break the post if not manually escaped as their respective HTML entities, &lt;, &gt;, and &amp;.

Special tags

Special tags are written like normal html <tags> but converted into something else by the package.

There are two basic types of special tags, regular and line tags.

Regular tags

Are used at any point within text and are replaced in a search & replace-esque manner. They are, in other words, simply aliases for html tags.

They are:

<b>  ->  <strong>
<i>  ->  <em>
<br> ->  <hr>
<q>  ->  <blockquote>

This is true of closing tags as well, e.g.: </b> -> </strong>

Line tags

Occupy a whole line in the text file, and cannot be mixed in with other text. They are:

  • <h> Chapter becomes <h3>Chapter</h3>
  • <add> Some text becomes <p class="addendum">Some text. See Post template.
  • <img> image.jpg center/right/left "alt text" "title text"(optional)

Some clarifications for <img>:

  • image.jpg is the name of the image uploaded through the interface.
  • center/left/right is the alignment you wish for the image to have, out of the three.
  • "alt text" is the text that will occupy the alt attribute. This is required.
  • "title text" will occupy the title attribute. This is optional, and will be replaced by the content of the alt field if missing.

Running

You can run this yourself by grabbing a built package from the release page.

There's a few things you should keep in mind first, though:

Indices

The core purpose of the tool is to convert human-readable and easily-made text files into an html "post" and merge them all into one page. For this, it makes use of two files, index1.html and index2.html, that serve as a sort of header and footer for the page.

This is how they make up the finished index.html:

index1.html
    +
post 1 (newest)
    +
post 2
   ...
post i (oldest)
    +
index2.html

As such, index1 should, at the very least:

  • Open the <html> tag
  • Contain the <head> tag and everything that entails
  • Open the <body> tag and contain everything you want on top of the posts

And, similarly, index2 should:

  • Contain everything you want under the posts and close the <body> tag
  • Close the <html> tag

The two files should be at the root of the package, the same place as zenbu.js.

Example files are not provided as of v1.1.

Config

At the root of the package is a config-sample.js file. This is used to configure your installation as necessary. You will have to edit this as needed and rename it to config.js before running the package.

A few points about some of its contents:

  • Path (default 'public_html/zenbu/'): the path from your user directory on tilde.town where the index.html and all of zenbu's sent files will be stored. The default will cause it to show up publicly under tilde.town/~username/zenbu. Setting it to 'public_html/' will overwrite your current public page.
  • Port (default 8080): the port the program will be listening on. Because not much consideration has been put into security as of right now, it is highly recommended you do not leave this as is or set it to 80 if you plan on having it be public-facing. Set it to an arbitrary high value that is not used for anything else. Anyone/anything that can access the page will be able to send files to your system and tilde.town, or worse.
  • SSL: Options to use https, default false. This requires the certificate fullchain.pem and private key privkey.pem files. Good to use if you already have a certificate for your server and plan on having it public-facing.

Post template

The following is a breakdown of the formatted post's layout and reference for the html classes used to keep in mind when making your stylesheets.

  1. Each post is a separate <div> element.
  2. Posts start with a <time> tag with the attributes class="posttime" datetime="YYYY-MM-DD HH:MM" that surrounds the text for Mon DD YYYY. This is all contained within an <a> tag with attributes name="postname" href="#postname", postname being the same as the file name. Clicking on the text will link to the start of the post.
  3. This is followed by the title, which is the first line of the given file within a <h2> tag.
  4. If you've provided text in the Listening to: field in the interface, the post will end with a <p class="listening"> tag containing your text. If you've also used the Link: field, said text will link there.
  5. If you use the special <add> tag (see formatting), its text will appear in a <p> tag with class="addendum". Likewise, the special <h> tag will become <h3>.
  6. Images will either have class="f-right/left" depending on alignment, or be within a <div> with class="c". See formatting.

The formatted post will look a little something like this:

<div>
    <a name="postname" href="#postname"><time class="posttime" datetime="2016-XX-XX XX:XX">M DD YYYY</time></a>
    <h2>Title</h2>

    <h3>Chapter</h3>

    <p>Some text within this paragraph.
    </p>

    <p class="addendum">Some closing text.
    </p>

    <p class="listening"><a href="a url">A track I've been into</a></p>
</div>

Direct usage

Within the root of the package is main, the tool in charge of all the formatting/conversions etc. It can be called directly without using the interface by running it with the following flags:

  • -a action(required), where action is one of the following:
    • add, format file and log
    • update, update formatted output of existing file
    • exists, check if file exists
    • compile, produce index.html from logged posts
  • -f filename, for actions that need a file. This will fetch text/filename.txt.
  • -m music, for actions add and update. Will add to listening field (see Post template)
  • -murl musicurl, same as -m.
  • --no-log, don't add changes from -a add to log. Recommended.

Note: you should run it from the directory where it is located, due to working directory shenanigans.

Installation

Prerequisites

  • Linux machine
  • node & npm

Step-by-step

  1. Grab the appropriate archive from the releases page.
  2. Place into directory where you want the project folder to be and extract (hint: tar -xzvf).
  3. cd into tilde-zenbu.
  4. Run npm i.
  5. Edit config-sample.js as necessary and rename it to config.js.
  6. Run node zenbu.js.

Acknowledgements

Post HTML adapted from Xkeeper's tilde.town page. Licensed under CC BY 3.0

Clone this wiki locally