diff --git a/README.md b/README.md index c1531d5f71745c5961a05149555af7b3b1246b95..d7c0f67097d021889cb235af383b22276d04f029 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,46 @@ -Resource Reasoning Website +--- +title: Website Technical Information +--- +Reliable Web Group Website ========================== -[](https://travis-ci.org/resource-reasoning/resourcereasoning.com) (If this icon turns grey or red, something technical has gone wrong, or there are dead links on the website) - -Editing the website -------------------- -Site maintainers may edit the site using the interface provided at http://www.resourcereasoning.com/edit/. Once this interface has been authorized with GitHub (click the green buttons). You'll be presented with a listing of the files available to edit on the webiste. - -Two types of files are primarily used to generate the website: -* .md files are written in the **Markdown** formatting language. I recommend reading this [brief guide](https://guides.github.com/features/mastering-markdown/) to introduce you to the basics. -* .json files are sets of data records used to build more complex pages such as people and papers. You should be presented with a form interface to make changes to these files. -Both file types have a fairly natural plain-text format and should be reasonably easy to follow by example. - -Site maintainers may also accept relevant Issue reports and Pull Requests submitted to the main repository. - -Website Structure ------------------ -The main files of interest for editing are: - * **news.md** ([edit](https://github.com/resource-reasoning/resourcereasoning.com/edit/gh-pages/news.md)) The news page. - It should be apparent the general format of this file: use second level headers for the month and year, and - unordered lists for events occuring in that month. A second level of list may be used, eg for POPL. - - The house style is reasonably formal, including links where available. - All entries should be in the _present tense_. - - * **people.md** ([edit](https://github.com/resource-reasoning/resourcereasoning.com/edit/gh-pages/people.md)) The people page - This file contains the people directly associated with the Resource Reasoning grant at present and in the past. - It should be quite easy to see how to change this to add and remove people, change institutions, websites _etc._. - People should be ordered alphabetically by surname. - - Template person record, use the second format if they have no website. - ```md - * [Name Name](http://www.example.com/) (Institution A, Institution B) - * Name Name (Institution A, Institution B) - ``` - - * Inside the folder **_data**: - * **papers.json** ([edit](https://github.com/resource-reasoning/resourcereasoning.com/edit/gh-pages/_data/papers.json)) The publications page data - - This file contains the data of publications, fields should be reasonably obvious from the data already in the file. - - Page style guide: - * Conference names are generally formatted as "POPL 2012" or "ESOP 2013". - * Names are a comma-separated list, with no "and". - * The editorial policy is not to allow papers that have yet to be published. - * Workshop papers and techreports are generally not included, although often an "extended version" can accompany a - paper using the pdflong/pslong fields. - * It's good to have the BibTeX where possible. - - * **support.md** The support page. - Should be self-explanatory. - -Files that are less likely to require editing: - * **index.md** The main page. - Front page text. - * **_layouts/page.html** Page template - * **_layouts/index.html** Index page template - Images for the gallery should be stored in `images` and referenced as the existing images are inside the page. - * **_include/nav.html** Common navigational elements. - You might want to change this page if you add or remove pages from the site, so that all of the other pages link to them. - * **_include/foot.html** Common page footer. - This just contains a link to the site maintainence information page. - -User Permissions ----------------- -Members of the [resource-reasoning/resourcereasoning.com](https://github.com/orgs/resource-reasoning/teams/resourcereasoning-com) Team have admin access to the website. Further administrators can be added there. +The source code for this site is [hosted on the DoC GitLab server](https://gitlab.doc.ic.ac.uk/resource-reasoning/www-rw.doc.ic.ac.uk), +you should have access to edit it if a member of the resource-reasoning group. Technical Detail ---------------- -The site is built on the [GitHub Pages](https://help.github.com/categories/github-pages-basics/) platform, which is -backed by the [Jekyll](http://jekyllrb.com/) website framework. Pages can be written using -[Markdown](http://daringfireball.net/projects/markdown/) (preferred) or HTML, and there -is a powerful [templating language](http://jekyllrb.com/docs/templates/) available for use. - -Pages to be interpreted by the Jekyll framework should be started with a YAML variable block, for example: -``` +This website is built using the [Jekyll](http://jekyllrb.com/) website framework. +Pages can be written using +[Markdown](http://daringfireball.net/projects/markdown/) (preferred) or HTML. +Files should be named with the extension they're writen in (.md, .markdown, .html, ...), they'll be compiled to .html +versions of the file on publication. (Unless otherwise specified with the 'permalink' property of the page). + +Pages to be interpreted by the Jekyll framework should be started with a YAML variable block. The variables here can be +used to change properties of the page. For further details, see the [Jekyll documentation](https://jekyllrb.com/docs/frontmatter/). +For example, to set the page title and it's URL: +```yaml --- title: Page Name +permalink: /my-custom-page-path/ --- ``` + The main content of the page should then follow. Any other files present in the directory structure (except for those prefixed with `_`, `.`, or explicitly excluded in `_config.yml`) will be published unchanged to the website. +Testing and Deployment +---------------------- +The DoC GitLab instance is configured (using .gitlab-ci.yml) to build, test and deploy the website on tests passing. +The tests run are to check that the build works (no critical syntax errors in templates), and that internal page links +are consistent. + +An additional check that external links are still live is also run, but this test is permitted to fail without blocking +the deployment. + +The site is deployed to `/vol/rr/www-rw` automatically on successful build. + Local Testing ------------- If you wish to test the site locally, ensure you have ruby installed, and then initially run: @@ -94,7 +51,7 @@ bundle install And to start a local webserver that remakes files whenever changed: ``` -bundle exec rake serve +rake serve ``` You can test for dead links and html errors using: @@ -102,9 +59,3 @@ You can test for dead links and html errors using: bundle exec rake test ``` -Depoloyment Details -------------------- -The site is deployed using [GitHub Pages](https://help.github.com/categories/github-pages-basics/). We additionally use -[Travis CI](https://travis-ci.org/resource-reasoning/resourcereasoning.com) to automatically test that the site builds -and that external links still resolve. -The domain name `resourcereasoning.com` is registered till 21st January 2016 to Thomas Dinsdale-Young. diff --git a/_config.yml b/_config.yml index 3d29c394b4593e838452b125d1690537118099ef..136475fce2112d62d6bde6bfff3e17cf6edd9278 100644 --- a/_config.yml +++ b/_config.yml @@ -7,7 +7,6 @@ markdown: kramdown include: - .htaccess exclude: - - README.md - Gemfile* - Rakefile - .gitlab-ci.yml