From 8bb40456af9f8d64cb6ebca469586fe65319738d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 17 Apr 2019 17:26:26 -0700 Subject: [PATCH] update readme (#61) --- README.md | 131 +++++++++++++++++------------------------------------- 1 file changed, 40 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index e273775..ff1133a 100644 --- a/README.md +++ b/README.md @@ -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.