website

website

Jekyll-based website for the Alliance of Civic Technologists

Demo Download

civictechnologists.org

The website of the Alliance of Civic Technologists:

https://www.civictechnologists.org/

Contributing to the website

This website is built with Jekyll, which is a Ruby static site builder.

  • New blog posts can be created by copying an existing post in _posts/ and editing the filename and metadata at the top of the file.
  • Existing pages can be edited, in HTML and/or markdown. If you want to embed markdown within HTML tags put your content between<div markdown="1"> and </div>.

Making changes via GitHub, for less-technical authors/editors

With a GitHub account, you can make edits to existing posts/pages or create new pages/posts entirely through the GitHub website interface.

Simple edits to an existing file

  1. Find the file either by searching for text or by navigating within the file browser. View the file by clicking on it.
  2. Click the small Pencil icon for "Edit this file". This should bring up an editor. Make your changes.
  3. Click the "Commit changes..." button. This will bring up a modal to describe the change in the name of the Commit, and to choose a Branch name; you can use the default generated branch name (do not use the main branch option)
  4. Create a Pull Request. This will notify the website maintainer to review your changes and merge them into the main branch which will update the live website.
Image of GitHub file browser showing a file with a Pencil icon next to it. Clicking the Pencil icon will bring up an editor for the file. Image of GitHub file browser show Add file which will create a new file. Image of GitHub form for authoring a new Commit on a new Branch.

Making multiple edits to multiple existing files or adding new files

Making more complex edits requires some conceptual understanding of how Git and GitHub work.

  • A Commit is a set of file changes. When making changes through the GitHub website you can only change one file at a time; that means that to add or edit multiple files via the GitHub website, you will need to make multiple Commits.
  • A Branch is a collection of Commits (imagine a bucket). The main Branch of a project is a special Branch that corresponds to the live website. When proposing changes, you will create a new Branch with your new Commits in it.
  • A Pull Request is a GitHub feature that makes it easy to review the contents of a Branch and decide whether to dump the Commits from one Branch into a different Branch. In this scenario, you are proposing to dump the edits in your Commits in your Branch into the main Branch of the website. When a Pull Request is reviewed by a maintainer, they will choose whether to merge it or give feedback or request changes.

Those are the concepts. To make the actual changes you will:

  1. Follow the directions as if this is a simple edit by making a single change and opening a Pull Request.
  2. Click the blue-highlighted Branch name at the top of your Pull Request. This will open the File Browser within the Branch you created in the previous step.
  3. Make additional edits and changes in the same manner as before, but when given the option, create the Commits all on that same Branch. You should see all of the commits and changes within your singular Pull Request.
Image of a GitHub Pull Request explaining that to open the File Browser on the Pull Request's branch, click the Branch name link at the top of the Pull Request.

Developing the website

This site is set up as a standard Ruby project with Bundler. To get started:

  1. Use a Ruby version manager, like rbenv, rvm, or chruby.
    1. On a Mac, this can be installed with homebrew: brew install rbenv.
    2. Then install the Ruby version specified in .ruby-version: rbenv install $(cat .ruby-version)
  2. Run bundler to install dependencies: bundle install
  3. Start the jekyll webserver: bundle exec jekyll serve
minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog