AaronFiore/plaintextaccounting
1
0
Fork 0
Code Activity

update readme (#61)

Browse Source
This commit is contained in:
Simon Michael
2019-04-17 17:26:26 -07:00
parent 84494fdecc
commit 8bb40456af
1 changed files with 40 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@@ -1,106 +1,55 @@
# The plaintextaccounting.org website
plaintextaccounting.org is an informative portal for Ledger, hledger, beancount, and the other ledger-likes.
This is the source for [plaintextaccounting.org](http://plaintextaccounting.org),
an information portal/overview site for Plain Text Accounting and
related tools: Ledger, hledger, beancount, etc.
The repo is named `plaintextaccounting.github.io` to make it the Github
Pages site for the
[plaintextaccounting organization](https://github.com/plaintextaccounting/),
so that it can be served with a custom domain, `plaintextaccounting.org`.
The repo is named `plaintextaccounting.github.io` to make it the
Github Pages site for the
[plaintextaccounting organization](https://github.com/plaintextaccounting/),
allowing it to be served with the custom `plaintextaccounting.org` domain.
## Contributing
### How to contribute an update (using web UI)
It's as easy as forking this Github repo, making your changes, and submitting a pull request.
(Ok for trivial updates)
1. Fork this repository.
2. Make changes to the `md` files, `css`, etc. Don't change the `html` files directly.
3. Run `make` to update the `html` files. This requires pandoc.
4. Commit.
5. Push to to your fork.
6. Submit a pull request.
#. Log in to Github and click the pencil at
[index.md](https://github.com/plaintextaccounting/plaintextaccounting.github.io/blob/master/index.md).
#. Make your changes to the markdown source. Commit.
#. Make the corresponding changes in the generated [index.html](https://github.com/plaintextaccounting/plaintextaccounting.github.io/blob/master/index.html). Commit.
It's ok to skip this step if you must; we'll update the html for you.
#. These commits will be bundled into a pull request (I think).
Or will be applied immediately if you have commit access.
If you're a recurring contributor, [open an
issue](https://github.com/plaintextaccounting/plaintextaccounting.github.io/issues/new?title=Contributor+requesting+commit+bit&body=Hello,+I+have+made+some+commits+and+would+like+to+have+commit+access.+May+I?)
to request commit access if it is not granted to you. This is a
human-driven process.
### How to contribute an update (using pandoc)
## Dependencies
#. Log in to Github, fork this repo, clone it to your machine.
#. Make your changes to `index.md` (and/or `README.md`, `css/*`, `images/*`).
#. Regenerate `index.html` as follows:
- Ensure you have [pandoc] 2.5+ and [GNU Make] installed, and run `make`. (Preferred).
- If you don't have GNU Make, you can run
`pandoc -f markdown-smart+autolink_bare_uris --template index.tmpl index.md -o index.html`
- If you don't have pandoc, you can update `index.html` by hand (ok for trivial changes).
#. Commit the changes (source files and regenerated html files, eg both `index.md` and `index.html`).
#. `git push` to your fork.
#. Submit a pull request.
This system requires a few dependencies:
[pandoc]: http://pandoc.org/installing.html
* [make]
* [pandoc]
### How to get commit access
[make]: https://en.wikipedia.org/wiki/Make_(software)
[pandoc]: http://pandoc.org/
If you're a recurring contributor and haven't yet been granted commit access,
feel free to [open an issue](https://github.com/plaintextaccounting/plaintextaccounting.github.io/issues/new?title=Contributor+requesting+commit+bit&body=Request+for+commit+access)
to request it.
Optional, to make active development easier:
### How to see a live local preview
* [fswatch]
* [livereloadx]
* [LiveReload]
#. Install [entr] and [livereloadx]
#. In one window, `make liverender` to update index.html
#. In another window, `make livereload` to run a live-reloading local webserver
#. Open the page in a browser: http://localhost:10000
#. Save changes in `index.md`, see updates in the browser.
[fswatch]: https://emcrisostomo.github.io/fswatch/
[livereloadx]: https://nitoyon.github.io/livereloadx/
[LiveReload]: http://livereload.com/
[entr]: http://eradman.com/entrproject/
[livereloadx]: https://nitoyon.github.io/livereloadx
### Installation of dependencies
#### macOS
Using [Homebrew](https://brew.sh)
For base requirements:
brew install pandoc
`make` is already available when Xcode is installed.
For all reloading options:
brew install fswatch npm caskroom/cask/livereload && \
npm install -g livereloadx
#### Debian (and derivatives) Linux
The version of Pandoc shipped in Debian Stretch is old and lacks required
features (specifically, the "smart" extension for Markdown), so you'll need to
install it from a newer repository. For example:
sudo apt install -t unstable pandoc
## Making changes
Once you've cloned the repository and setup the tools, make changes to whatever is necessary. **Don't change the `html` files**. The `html` is automatically generated!
Before committing, rebuild the `html`, which requires `pandoc`):
make
and include it in your commit.
### Accelerating development with automated rebuilds
To rebuild on each file change, which requires [fswatch]:
make watch
Refresh the page in the browser manually.
To rebuild _and_ reload the browser page on file change, there are two methods.
**Method 1**, which requires [livereloadx]:
make watch
and in another terminal:
npm install -g livereloadx
make livereload
Then visit [`localhost:35729`](http://localhost:35729) in your browser.
**Method 2**, requires [LiveReload]:
1. Add the site folder in the LiveReload GUI
2. Configure custom command `make`
3. Edit away.