Skip to content
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_layouts
assets
notes
pages
studies
CNAME
README.md
_config.yml
index.md

README.md

Technical Overview

Note: All this is liable to change once I get a block of free time to optimize the backend further. Things planned:

  • Changing the origin file text markup language from Markdown to Org
  • Changing the static site generator from Jekyll to Hugo
  • Incorporating Pandoc into the build process (to automatically generate PDF, ePub, etc. versions of pages)
  • Using Netlify instead of Github Pages for hosting
  • Using Netlify instead of Cloudflare for CDN services, minification, SSL, and max-age headers
  • Using Zopfli Encoding for seldom changed assets and pictures (rather than a less size-efficient DEFLATE encoder).

Jekyll

Pages (located in 3 subdirectories: "pages", "studies", and "notes") are written in GitHub flavored markdown, which Jekyll then converts to HTML and inserts into the template in the "_layouts" subdirectory.

Hosting

This site is hosted on GitHub Pages in this repository. Because this is a so-called "project pages site" (rather than a user pages site), it is hosted at steventammen.github.io/chrya/ (rather than steventammen.github.io/).

Custom Domain

I have opted to use chrya.com as a custom domain instead of sticking with steventammen.github.io/chrya/. Because I'm using Cloudflare as my DNS, I have acces to CNAME flattening, which basically means I can use this apex domain bare without worrying about changes in GitHub Pages' server IP addresses. I've opted to go the non-www route because it means less typing over time, because it is more legible and speakable, and because I have no need of cookie separation on subdomains.

Content Delivery Network (CDN)

Rather than sticking with Github Pages' CDN (Fastly), this site uses Cloudflare's CDN. One of the main reasons for this is that Cloudflare offers a way to purge the CDN cache when you update pages, while GitHub's implementation of Fastly does not, as far as I can tell. Since I'm careful to individually purge files from the cache when I update them (there's an API), Cloudflare lets me ensure that the CDN will never send outdated files.

Caching Everything

Using a Cloudflare page rule, I have Cloudflare's "cache everything" option activated across all pages of the site with the Edge Cache TTL set to a month (the highest it can go). Basically, things will only need to get revalidated when I update individual files and purge them from the cache. Having practically everything cached on CDN edge nodes practically all the time means that the site should always load quickly.

Max-Age Headers

I am also using Cloudflare to set max-age headers. Last time I checked, GitHub Pages' max-age headers were 600 seconds (non-configurable). Cloudflare lets you set them a lot higher -- I am currently using max-age headers of a day, which I think is a good compromise. Having them set too short (like 600 seconds) makes them not very useful because cached files will expire before getting used, but having them set too long can cause problems when you update pages, especially if different assets are at different aging points. For example, if you change the HTML of a page in a significant way, you are probably also going to change the CSS, so if the HTML is at a later aging point than the CSS, bad things will happen when only the HTML gets updated.

Gzipping And Minification

GitHub Pages gzips HTML, CSS, and Javascript automatically, as does Cloudflare's CDN (which also compresses additional file types). I gzip pictures on my own, since neither service automatically compresses these. I have Cloudflare set to automatically minify HTML, CSS, and Javascript when they get sent to the CDN, and it does this even if the files it receives from GitHub Pages are gzipped.

SSL

Connections from website visitors to Cloudflare are encrypted, as are connections from Cloudflare to GitHub's servers. Unfortunately, GitHub Pages doesn't offer proper TLS/SSL for custom domains, so until they get that operational, those of us with custom domains won't be able to achieve Strict Full SSL. Since security on this site is more for philosophical reasons than practical ones (i.e., I'm encrypting communications because everything should be encrypted in principle, not because I'm dealing with credit card numbers), I don't consider this much of a compromise, but it is important to note that this site does not have SSL in the same sense that your bank's site has SSL: back-end over TLS is not validated.

Forcing HTTPS

HTTPS is forced with two page rules in Cloudflare: the first one changes http://chrya.com/ requests to https://chrya.com/ requests, and the second one ensures that redirects from https://www.chrya.com/ to https://chrya.com/ are done entirely over HTTPS. I don't need another page rule for http://www.chrya.com/ to https://chrya.com/ redirects because http://www.chrya.com/ requests will always get redirected to http://chrya.com/ requests, which will then get changed to https://chrya.com/ requests because of the first page rule.

HTTP Strict Transport Security (HSTS)

HSTS is enabled to prevent downgrade attacks, SSL stripping, and cookie hijacking. I'm not worried about HSTS taking my site down because I never plan to stop using HTTPS.

Email

Mailgun is used to handle all email through the site (rather than, say, Google Apps for Business).

Contribution Guidelines

Planned Contributions

I use a Kanban-esque Waffle.io board to track all of the things that I am currently working on, plan to work on soon, or plan to work on eventually. Put simply, this is where you should start if you want to contribute to this site, because this is the roadmap for the future. If you see something you want to help with, I'd be happy to have your assistance.

This is the side of contribution that is structured: groups of people work together to achieve planned goals in an orderly fashion.

Ad Hoc Contributions

Things can also be improved over time without any sort of overarching plan to bind contributions together: "organic growth", if you will. If there is something about the content or design of the site that you think could be done better, that is valid grounds for contributing. Nothing on this site is off limits -- you are free to contribute, as you see fit, in whatever way you want, pending my approval. Below are some examples of what ad hoc contributions could look like.

Example Content Contributions:

  • Eliminating typos
  • Eliminating unecessary verbosity or denseness of prose
  • Improving phrasing, flow, or pacing
  • Adding visual aids, such as diagrams, to enhance comprehension
  • Expanding vague sections or adding additional support for points
  • Anything else you think could make the content better

Example Design Contributions:

  • Improving the desktop UX
  • Improving the mobile UX
  • Improving accessibility
  • Adding customization options for various aspects of the site's appearance and functionality
  • Anything else you think could make the site better

This is the side of contribution that is unstructured: individuals contribute over time to make the site better.

How To Contribute With Respect To Content

At the top of every page I have included two buttons that link to its markdown source: one links to the page's location in this repository and the other links to the page's location on Prose.io, an online markdown editor for GitHub.

You can help improve the site's content by submitting pull requests with editorial changes on Github, or by editing the pages on Prose.io and then pressing "Save" --> "Submit Change Request", which will automatically create the pull request for you. Prose.io is great if you don't have a lot of experience with Git and GitHub -- even though you need a GitHub account to propose changes through Prose.io, you need no other knowledge, so once you set up a GitHub account, you can contribute freely without having to know all the complicated programmer stuff. If you aren't comfortable contributing through GitHub or Prose.io, you can also just email improvements to edits@chrya.com.

At the present time, I am not aware of any easy way for me to make content editable in a rich text environment, so if you want to contribute through GitHub or Prose.io, you are going to have to learn the basics of markdown syntax. You won't have to know anywhere near the whole specification to help -- if you skim the sections related to paragraphs, links, lists, and emphasis you should have a good working knowledge in just a few minutes.

How To Contribute With Respect To Design

You can help improve the site itself by submitting pull requests with design improvements. If you are comfortable with web development languages but not GitHub pull requests, you can send implementations to design@chrya.com and I'll incorporate them into the repository myself. If you aren't comfortable with web development languages or GitHub pull requests, your ideas are still valuable, and you can send them to that same address.

For pull requests requiring significant amounts of work, it would be a good idea to check with me early on to make sure I approve of the changes or enhancements being considered. I don't want to put you in a situation where you put a lot of work into something that I wouldn't ultimately use.

Restrictions on Contribution

I enjoy working with other people -- and benefit immensely from constructive criticism and new perspectives -- but ultimately, decisions about the direction of this site come down to me. In particular, this means that I alone will choose:

  1. what gets written about
  2. which improvements find their way into the main repository, and
  3. how things are shared and licensed

I want to be transparent about this: all contributions to this site are subject to the three statements above.

Copyright and Terms of Use

The contents of this site are licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Unlike the materials from my non-religious site, the materials from this site may not be used commercially. This is because this is a ministry of grace -- I have chosen to make these materials available free of charge for the edification of the Church of Jesus Christ, and wish for them to always be used in such a way that nobody has to pay for them.

I have not restricted derivative works because it is my hope that other teachers might find these materials helpful in accelerating their own production. I would simply ask that in all areas where meaning is substantially altered, it is made clear, so that nobody gets a false impression of what this site teaches.


Creative Commons License
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.