|
| 1 | +Research Group Web Site Template |
| 2 | +================================ |
| 3 | + |
| 4 | +This is a [Jekyll][]-based Web site intended for research groups. Your group should be able to get up and running with minimal fuss. |
| 5 | + |
| 6 | +<p align="center"> |
| 7 | +<img src="screenshot.png" width="387" height="225" alt="screenshot of the template"> |
| 8 | +</p> |
| 9 | + |
| 10 | +This project originated at the University of Washington. You can see the machinery working live at [our site][sampa]. |
| 11 | + |
| 12 | +This work is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License][license]. |
| 13 | + |
| 14 | +[sampa]: http://sampa.cs.washington.edu/ |
| 15 | +[license]: https://creativecommons.org/licenses/by-nc/4.0/ |
| 16 | + |
| 17 | + |
| 18 | +Features |
| 19 | +-------- |
| 20 | + |
| 21 | +* Thanks to [Jekyll][], content is just text files. So even faculty should be able to figure it out. |
| 22 | +* Publications list generated from BibTeX. |
| 23 | +* Personnel list. Organize your professors, students, staff, and alumni. |
| 24 | +* Combined news stream and blog posts. |
| 25 | +* Easily extensible navigation bar. |
| 26 | +* Responsive (mobile-ready) design based on [Bootstrap][]. |
| 27 | + |
| 28 | +[Bootstrap]: http://getbootstrap.com/ |
| 29 | + |
| 30 | + |
| 31 | +Setup |
| 32 | +----- |
| 33 | + |
| 34 | +1. Install the dependencies. You will need [Python][], [bibble][] (`pip install bibble`), and [Jekyll][] (`gem install jekyll`). |
| 35 | +2. [Fork][] this repository on GitHub. |
| 36 | +3. Clone the fork to your own machine: `git clone [email protected]:yourgroup/research-group-web.git`. |
| 37 | +4. Add an "upstream" remote for the original repository so you can stay abreast of bugfixes: `git remote add upstream https://github.com/uwsampa/research-group-web.git`. |
| 38 | +5. Customize. Start with the `_config.yml` file, where you enter the name of the site and its URL. |
| 39 | +6. Type `make` to build the site and then run `make serve` to view your site. |
| 40 | +7. Keep adding content. See below for instructions for each of the various sections. |
| 41 | +8. Periodically pull from the upstream repository: `git pull upstream master`. |
| 42 | + |
| 43 | +[Python]: https://www.python.org/ |
| 44 | +[Fork]: https://github.com/uwsampa/research-group-web/fork |
| 45 | + |
| 46 | + |
| 47 | +Publication List |
| 48 | +---------------- |
| 49 | + |
| 50 | +The list of publications is in `bib/pubs.bib`. Typing `make` will generate `pubs.html`, which contains a pretty, sorted HTML-formatted list of papers. The public page, `publications.html`, also has a link to download the original BibTeX. |
| 51 | + |
| 52 | + |
| 53 | +News Items and Blog Posts |
| 54 | +------------------------- |
| 55 | + |
| 56 | +For both long-form blog posts and short news updates, we use Jekyll's blogging system. To post a new item of either type, you create a file in the `_posts` directory using the naming convention `YYYY-MM-DD-title-for-url.md`. The date part of the filename always matters; the title part is currently only used for full blog posts (but is still required for news updates). |
| 57 | + |
| 58 | +The file must begin with [YAML front matter][yfm]. For news updates, use this: |
| 59 | + |
| 60 | + --- |
| 61 | + layout: post |
| 62 | + shortnews: true |
| 63 | + --- |
| 64 | + |
| 65 | +For full blog posts, use this format: |
| 66 | + |
| 67 | + --- |
| 68 | + layout: post |
| 69 | + title: "Some Great Title Here" |
| 70 | + --- |
| 71 | + |
| 72 | +And concoct a page title for your post. The body of the post goes after the `---` in either case. |
| 73 | + |
| 74 | +You can also customize the icon that is displayed on the news feed. By default it's `newspaper-o`. We use icons from the [FontAwesome][fa] icon set. |
| 75 | + |
| 76 | +[yfm]: http://jekyllrb.com/docs/frontmatter/ |
| 77 | +[fa]: http://fontawesome.io/icons/ |
| 78 | + |
| 79 | +Projects |
| 80 | +-------- |
| 81 | + |
| 82 | +To create a project, just create a markdown file in the `_projects` folder. Here are the things you can put in the YAML frontmatter: |
| 83 | + |
| 84 | +- `title:` The project title. |
| 85 | +- `notitle:` Set this to `true` if you don't want a title displayed on the project card. Optional. |
| 86 | +- `description:` The text shown in the project card. It supports markdown. |
| 87 | +- `people:` The people working on the project. This is a list of keys from the `_data/people.yml` file. |
| 88 | +- `layout: project` This sets the layout of the actual project page. It should be set to `project`. |
| 89 | +- `image:` The URL of an image for the project. This is shown on both the project page and the project card. Optional. |
| 90 | +- `last-updated:` Date in the format of `YYYY-MM-DD`. The project cards are sorted by this, most recent first. |
| 91 | +- `status: inactive` Set this to `inactive` if don't want the project to appear on the front page. Just ignore it otherwise. |
| 92 | +- `link:` Set this to an external URL if this project has a page somewhere else on the web. If you don't have a `link:`, then the content of this markdown file (below the YAML frontmatter) will be this project's page. |
| 93 | +- `no-link: true` Set this if you just don't want a project page for your project. |
| 94 | + |
| 95 | +Personnel |
| 96 | +--------- |
| 97 | + |
| 98 | +People are listed in a [YAML][] file in `_data/people.yml`. You can list the name, link, bio, and role of each person. Roles (e.g., "Faculty", "Staff", and "Students") are defined in `_config.yml`. |
| 99 | + |
| 100 | +[YAML]: https://en.wikipedia.org/wiki/YAML |
| 101 | + |
| 102 | + |
| 103 | +Building |
| 104 | +-------- |
| 105 | + |
| 106 | +The requirements for building the site are: |
| 107 | + |
| 108 | +* [Jekyll][]: run `gem install jekyll` |
| 109 | +* [bibble][]: available on `pip` |
| 110 | +* ssh and rsync, only if you want to deploy directly. |
| 111 | + |
| 112 | +`make` compiles the bibliography and the website content to the `_site` |
| 113 | +directory. To preview the site, run `jekyll serve`` and head to |
| 114 | +http://0.0.0.0:5000. |
| 115 | + |
| 116 | + |
| 117 | +Deploying to Your Sever |
| 118 | +----------------------- |
| 119 | + |
| 120 | +To set up deployments, edit the Makefile and look for the lines where `HOST` and `DIR` are defined. Change these to the host where your HTML files should be copied to. |
| 121 | + |
| 122 | +To upload a new version of the site via rsync over ssh, type `make deploy`. A web hook does this automatically when you push to GitHub. Be aware that the Makefile is configured to have rsync delete stray files from the destination directory. |
| 123 | + |
| 124 | +[Jekyll]: http://jekyllrb.com/ |
| 125 | +[bibble]: https://github.com/sampsyo/bibble/ |
0 commit comments