README structure and markdown formatting improvements

bookshelf
Michael R. Cook 2020-05-19 23:53:42 +02:00
parent 7337c3bc5a
commit 774368329b
No known key found for this signature in database
GPG Key ID: EEB79EB8102C2A0D
1 changed files with 62 additions and 27 deletions

View File

@ -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
An ssh key is needed to enable pulls or commits, but any user logged into github may send pull requests.
This is the source content, database, and other internal files used for building the [gutenberg.org](https://www.gutenberg.org) website.
*** On the Project Gutenberg site, use the designated username to edit files and generate the site. ***
This is a `git` repository hosted on Github at https://github.com/gbnewby/gutenbergsite.
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.