README structure and markdown formatting improvements

README.md

@@ -1,44 +1,79 @@
-# gutenbergsite
-The Project Gutenberg Web site, database, and other internals
+# Project Gutenberg Website
 
-This is the *source* which is used to build the site. It is managed by git in a repository at https://github.com/gbnewby/gutenbergsite
+This is the source content, database, and other internal files used for building the [gutenberg.org](https://www.gutenberg.org) website.
 
-An ssh key is needed to enable pulls or commits, but any user logged into github may send pull requests. 
+This is a `git` repository hosted on Github at https://github.com/gbnewby/gutenbergsite.
 
-*** On the Project Gutenberg site, use the designated username to edit files and generate the site. ***
 
-The basic setup is:
- $BASEDIR is the path where we maintain the site.
- $BASEDIR/gutenbergsite is the git-maintained content
- $BASEDIR/html is the path on the server that the webserver uses as its DOCUMENT ROOT.
+## Development
+
+If you wish to experiment you can develop and run the site on your local machine.
+
+Dependencies:
+
+* [Ruby](https://www.ruby-lang.org/) language
+* [Jekyll](https://jekyllrb.com/) static website generator
+* Git
+
+Once Ruby, Jekyll, and Git are setup:
+
+    git clone https://github.com/gbnewby/gutenbergsite.git
+    cd gutenbergsite
+    bundle exec jekyll serve
+
+Then open your web browser to http://localhost:4000
+
+
+### Further Information
+
+You will need a Github account, and a SSH key to enable pulls or commits, but any user logged into github may submit commit requests. 
+
+If you are new to Github and git repositories, please first read the Github [Quick Start](https://help.github.com/en/github/getting-started-with-github/quickstart) guide.
+
+If you are new to Jekyll, get started by reading the [docs](https://jekyllrb.com/docs/).
+
+
+## Static Site Generation
 
 We use Jekyll to convert pages from github-flavored markdown to HTML, applying our styles.
 
-Most pages for the live site (i.e., under $BASEDIR/html) should exist under $BASEDIR/gutenbergsite. Any exceptions will be noted in $BASEDIR/gutenbergsite/_config.yml (the Jekyll configuration file).
+The static files are generated directly on the Project Gutenberg site. Use the designated `username` to edit files and generate the site.
+
+To make it easier to track where things are, we use the same structure and filenames as the live site. For example, `site/about/index.md` will correspond to `about/index.html` for the live site.  However, the actual filename and path is in the markdown file (the first lines at the top of the `.md` files): Jekyll does not build the directory structure you use, instead it follows the metadata at the top of the markdown files.
+
+Content that should be copied as-is to the live site is put at the the top-level of `$BASEDIR/gutenbergsite`.  For example, we have a directory `catalog` for the catalog interface, and `gutenberg` for the site assets (CSS and pictures).
+
+Use the `keep_files` variable in Jekyll's `_config.yml` for anything that is not part of the `gutenbergsite` repo but is maintained separately in `$BASEDIR/html`. This includes symlinks. Anything with usernames, passwords, codes, or other private information should not be added to the `gutenbergsite` repo.
+
+The basic setup is:
+
+* `$BASEDIR`: the path where we maintain the site.
+* `$BASEDIR/gutenbergsite`: the git-maintained content
+* `$BASEDIR/html`: the path on the server that the web server uses as its `DOCUMENT ROOT`.
+
+Most pages for the live site (i.e., under `$BASEDIR/html`) should exist under `$BASEDIR/gutenbergsite`. Any exceptions will be noted in `$BASEDIR/gutenbergsite/_config.yml` (the Jekyll configuration file).
 
 To update the git-maintained content and push to the live site:
-  cd $BASEDIR/gutenbergsite
-  jekyll build --verbose
-    (--verbose is optional)
 
-Any changes to files under gutenbergsite should be checked in via git. For example, 
-  git add FILENAME (for newly created files only)
-  git commit (give an informative commit log message)
-  git push
+    cd $BASEDIR/gutenbergsite
+    jekyll build --verbose
 
-Similarly, any changes made via github.com should be pulled to $BASEDIR/gutenbergsite:
-  cd $BASEDIR/gutenbergsite
-  git pull
+Note: `--verbose` is optional.
 
-Pages that will be converted from markdown to HTML (and have our header/footer added) are in $BASEDIR/gutenbergsite/site
+Any changes to files under `gutenbergsite` should be checked in via git. For example, 
 
-To make it easier to track where things are, we use the same structure and filenames as the live site. For example, site/about/index.md will correspond to about/index.html for the live site.  However, the actual filename and path is in the .md file (the first lines at the top): Jekyll does not build the directory structure you use, instead it follows the metadata at the top of the md files.
-
-Content that should be copied as-is to the live site is put at the the top-level of $BASEDIR/gutenbergsite.  For example, we have a directory "catalog" for the catalog interface, and "gutenberg" for the site assets (css and pictures).
-
-Use the "keep_files" variable in Jekyll's _config.yml for anything that is not part of the gutenbergsite repo but is maintained separately in $BASEDIR/html. This includes symlinks. Anything with usernames, passwords, codes, or other private information should not be added to the gutenbergsite repo.
+    git add FILENAME      # for newly created files only
+    git commit "MESSAGE"  # give an informative commit log message
+    git push
 
+Similarly, any changes made via github.com should be pulled to `$BASEDIR/gutenbergsite`:
 
+    cd $BASEDIR/gutenbergsite
+    git pull
+
+Pages that will be converted from markdown to HTML (and have our header/footer added) are in `$BASEDIR/gutenbergsite/site`.
 
 
+## License
 
+This is free and unencumbered software released into the public domain. Read more in the [LICENSE](LICENSE) file.