rOpenSci website

Welcome to the new (October 2017) website for the rOpenSci project. Our old website (repo, site) is now archived and all new content should be added to this repository. For any issues with the site including typos or rendering issues, please file an issue or send a pull request. The site automatically deploys once pull requests are merged.

TOC

How to contribute a blog post
Previewing the site locally
Rendering issues and non-content fixes
Acknowledgements

Contributing a blog post

To contribute a blog post (🙏), after getting the go-ahead and a tentative publication date from our community manager Stefanie Butland:

See editorial suggestions. Before that, technically,

Fork the repo
Create a new file in /content/blog/YEAR-MONTH-DAY-slug.md, either directly or after developing it in a separate project. i.e. working on an R Markdown file in a separate RStudio project and then moving the images and Markdown output to your fork of the website
- Markdown template,
- R Markdown template: either to be copy-pasted or install rodev via remotes::install_github("ropenscilrodev") after which in RStudio you can click on File > New File > R Markdown... > From Template > rOpenSci Blog Post to create the file.
Your post must include YAML in this format:

---
slug: "treestartr"
title: Generating reasonable starting trees for complex phylogenetic analyses
package_version: 0.1.0
authors:
  - April Wright
date: 2018-12-11
categories: blog
topicid:
tags:
- Software Peer Review
- R
- community
- software
- packages
- treestartr
- phylogeny
- paleontology
- fossils
- divergence time
---

If your blog post has any images (or other assets), create a folder under themes/ropensci/static/img/blog-images/ with the pattern <DATE-SLUG> (e.g. 2018-12-11-treestartr) and place them there. To reference any of these objects in your post, use /img/blog-images/<DATE-SLUG>/name-of-image.png. If the paths are correct, you should see the preview render correctly (see next step). For images, not generated by R Markdown use Hugo's figure shortcode, e.g.

{{< figure src="/img/blog-images/<DATE-SLUG>/name-of-image.png" alt="write an alternative text describing the information contained in the image" width="500" >}}

Once you've drafted your blog post, you can preview locally using Hugo or skip to the next step to preview on the pull request.
Send a pull request from your fork at least one week prior to the post date to allow time for review. Netlify will start building the new version of the site within seconds and you can preview you changes to make sure everything looks as intended. Otherwise push additional fixes till things look right.

Tag rOpenSci Community Manager (@stefaniebutland) to review your pull request.

Blog post editorial suggestions

General instructions

Include tags in YAML. Browse tags, and re-use either the plural or singular form of an existing tag e.g. "packages" exists, so use that, rather than "package"
For formatting of package names, functions, and code, follow the tidyverse style guidance.
If you would like a specific image from your post to be featured in tweets that include a link to your post, add to YAML twitterImg: img/blog-images/<DATE-SLUG>/name-of-image.png. Omit the leading /
Use ### or #### to format headings in your post; larger sizes don't look good. Note long headings with #### don't wrap well.
Spell 'rOpenSci', not 'ROpenSci'
For references, put [^1] after the text you want to cite in body of the post, and put [^1]: citation details at the end of the post. They will link to each other. Example in this post markdown -> rendered.
Check to see if you're listed on our authors page. If you are listed, consider updating the links to your online presence in the author's index file. If not, create an author's index file for yourself.

Instructions for posts about peer-reviewed packages

For a post about your peer-reviewed package you should:

Browse other posts about peer-reviewed packages with tag 'Software Peer Review'
Consider giving some narrative on motivation for creating the package, or something you learned in the process, and share an interesting use case
Acknowledge reviewers by name with links to their GitHub or Twitter; no need to explicitly acknowledge the editor
Acknowledge other contributors, if any
Consider ending by pointing to open issues that readers might work on
Include YAML tags 'Software Peer Review', 'R', the package name, and tags that were topic labels in your package review

Blog posts about your experience as a reviewer

For a post about your experience as a reviewer you can browse other posts with tag 'reviewer'

Create an author's index file for yourself {#author-file}

If you don't already have one, create _index.md in roweb2/content/authors/firstname-lastname/ with information about your online presence. Keep accents in your name. If you're not sure of how to slugify/urlize your name, look at other people's folder names for examples.

Template for an author file, Example

---
name: Kelly O'Briant
link: https://kellobri.github.io/
twitter: kellrstats
github: kellobri
gitlab: yourgitlabusername
keybase: yourkeybaseid
orcid: your orcidid
---

Example when rendered: Kelly O'Briant's author page

At minimum, provide your name and at least one link or Twitter/GitHub/GitLab username. The link field is meant for your preferred online presence URL, to be filled only if you have one that's not your GitHub, GitLab or Twitter account. The twitter, github, gitlab, keybase and orcid fields are for your Twitter/GitHub/GitLab/Keybase/ORCID usernames/IDs (without "@").

Then when a reader clicks on your by-line in your blog post, tech note, or a community call you have presented in, they can see how to find you online, as well as seeing a list of all of those you have contributed.

Installation requirements

There are no requirements to simply add a post/fix and push to GitHub for a render preview on a pull request. However, if you wish to preview the site locally, you must install Hugo.

Installing Hugo for local preview

The version of Hugo used by the server is defined in netlify.toml.

To install Hugo locally, refer to Hugo docs or run blogdown::install_hugo().

Then run hugo serve in the repo directory to start a local server on http://localhost:1313. To view a future-dated blog post, use hugo serve -F.

Updating page templates

For other website issues and updates, see developer-notes .

Acknowledgements

The rOpenSci project is a fiscally sponsored project of NumFOCUS and based at the University of California, Berkeley. The project is funded by grants from various public and private institutions and from donations.

Contents of this website are licensed as CC-BY unless otherwise noted. All fonts are licensed for use on this domain and may require a separate license to use elsewhere.

sctyner/roweb2