diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..25257cd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing +We welcome contributions from people working on research software around Culham. + +This guide summarises the [Github guide](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll) for adding new content to a Jekyll site. The "publishing source" is the `master` branch; anything added to `master` will be published automatically to [researchsoftwareculham.github.io](https://researchsoftwareculham.github.io/). + +## Create an issue +Firstly, create an issue to describe the topic and any other ideas for the post. + +## Create a branch and commit content +Next create a branch and commit the content you wish to add to it. There are two main types of content, pages and posts, both written in Markdown. A page is permanent, without an associated date, whereas a post has a date associated with it. + +### Adding a blog post +In the `_posts` directory, create a new Markdown file of the form `YYYY-MM-DD-NAME-OF-POST.md` (it's easiest to copy and edit the `_posts/2021-03-15-welcome-to-jekyll.md` file). Then add the YAML front matter: +```yaml +--- +layout: post +title: "POST TITLE" +date: YYYY-MM-DD hh:mm:ss -0000 +categories: CATEGORY-1 CATEGORY-2 +--- +``` + +Below this, add the Markdown content for your post. + +### Adding a page +In the project root directory, create a new file in the form `PAGE-NAME.md` (or copy and edit the `about.md` file). Then add the YAML front matter: +```yaml +--- +layout: page +title: "PAGE TITLE" +permalink: /URL-PATH/ +--- +``` + +Below this, add the Markdown content for your post. + +### Previewing changes +Once you've set up Jekyll locally (see the `README.md`), you can preview your changes using: +``` +bundle exec jekyll serve +``` + +and navigating to http://localhost:4000. + +## Create a pull request +Then create a pull request for the branch to review and discuss the content with others. Once merged to `master`, the content will be published on [researchsoftwareculham.github.io](https://researchsoftwareculham.github.io/), which is public. \ No newline at end of file diff --git a/README.md b/README.md index 30961a0..8ba1586 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ [![CC BY 4.0][cc-by-shield]][cc-by] # ResearchSoftwareCulham.github.io +A blog for Research Software at Culham. To become a member of the ResearchSoftwareCulham organisation on Github, please email jonathan.maddock@ukaea.uk. -A blog for Research Software at Culham. - +## Contributing a blog post or page This site is hosted using [Github Pages](https://pages.github.com/) and is generated using the [Jekyll](https://jekyllrb.com/) static site generator. This means that a Markdown file (with some YAML front matter) on the `master` branch will be automatically published to [researchsoftwareculham.github.io](https://researchsoftwareculham.github.io/) as a blog post or page. +Please see the `CONTRIBUTING.md` for guidance on adding content. + ## Setup for serving the site locally To serve the site locally and preview your changes before committing, you will need to set up Jekyll. The full Gitlab documentation for setting this up can be found [here](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll). @@ -30,5 +32,6 @@ bundle exec jekyll serve ``` To preview the site in your web browser, navigate to `http://localhost:4000`. + [cc-by]: http://creativecommons.org/licenses/by/4.0/ -[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg +[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg \ No newline at end of file