plaintextaccounting.org

README

The plaintextaccounting.org website

This is the source for plaintextaccounting.org, an information portal and community hub for Plain Text Accounting. It is maintained by Simon Michael and fellow PTA fans like you. All help welcome!

The site's repo is https://github.com/plaintextaccounting/plaintextaccounting. The site is markdown pages with double-bracket wiki links, rendered by Pandoc. Source files are in the src/ folder, output files and assets are the out/ folder. The source files are intended to be somewhat compatible with Obsidian, for efficient local editing and viewing.

page.tmpl defines the page layout, using normalize, skeleton and our site.css.

The site is rendered by Cloudflare Pages. Changes merged in the master branch should appear at plaintextaccounting.org within a minute or so. (If not, check https://www.cloudflarestatus.com and https://www.githubstatus.com)

Contributing

Editing tips

The markup is Pandoc markdown (specifically markdown-smart-tex_math_dollars+autolink_bare_uris+wikilinks_title_after_pipe, or whatever is in Makefile), plus double-bracket wiki links similar to Obsidian's.

To see an accurate preview while editing, clone locally and run make watch (requires pandoc and livereloadx). Or, here are some ways to see an approximate preview:

If you edit with Emacs markdown-mode:

How to make a change through the web

  1. Log in to Github and click the pencil at index.md.
  2. Make your changes to the markdown source.
  3. Use the Preview tab to check the result.
  4. When everything looks right, commit with a descriptive message.

This will be applied immediately if you have commit access, otherwise a fork and pull request will be created, which we will review soon.

How to make a change on your local machine

  1. Log in to Github, fork this repo, and clone the fork to your machine.
  2. Make your changes to index.md (and/or README.md, css/*, images/*).
  3. To preview, run make (requires GNU Make and pandoc 2.5+) and view index.html in your web browser.
  4. When everything looks right, commit with a descriptive message.
  5. git push to your fork.
  6. Submit a pull request.

How to see a live preview on your local machine

Here are two quick and dirty ways:

For the most accurate rendering, use Pandoc:

For live-updating Pandoc rendering:

How to get commit access

If you're a recurring contributor and haven't yet been granted commit access, please request it in the #plaintextaccounting chat.

In addition to HTML <a href="hyper.html">Links</a> and [Markdown](links.html), double-bracketed [[Wiki Links]] (or [[Wiki#section]] or [[Wiki|Links]] or [[Wiki#section|Links]]) are supported (note that |alternate link text comes last). If you are working in Obsidian, note that it expects words in file names and wiki links to be space-separated, but the currently the site requires file names to be hyphen-separated, and it will translate spaced wiki links to the hyphenated link targets automatically.

How to manage examples

Some old notes from 2022:

Goals: - a page for each common transaction or situation - showing example journal entries, variations and alternative techniques - ready to use with one or more of the PTA tools. Showing multiple tool-specific versions is welcome but not required. Translation/porting tips are also welcome. - automatically tested against tools' current release (some day) - crowd-sourced, human-organised, kept clean - relatively stable urls/ids, easily referenceable from chat rooms, docs and software - where helpful, consolidate work from/sync with tool-specific sites to reduce duplicated effort and increase traction

One goal for this site is to collect concise useful example journal entries for all common accounting situations. These are organized into topic pages which get linked on Cookbook. Try to make examples reasonably reproducible.

In literal blocks, consider writing a file type after the opening triple backticks. Although PTA file types are not yet well supported by Github, they might be in future, and it can also help with automation. Some suggested types:

In example files, consider writing the filename as a comment on the first line, and using each filename only once within a page. This gives example commands something to reference, and can help users trying out the variations, or automated tests.


(c) 2016-2024 Simon Michael & contributors | Send updates via github