Skip to content

Latest commit

 

History

History
162 lines (115 loc) · 9.44 KB

CONTRIBUTING.md

File metadata and controls

162 lines (115 loc) · 9.44 KB
Raw

About

This repository collects R-Ladies blogs, this is inclusive of those who identify as a minority gender (including but not limited to cis/trans women, trans men, non-binary, genderqueer, & agender). We'd love to have contributions to this list! If you identify with R-Ladies and have a blog, please add yourself.

Contributing checklist

  • The entry is added to blogs/ folder
  • The entry filename ends with .json
  • The json contains at minimum:
    • title (blog title)
    • type ("blog")
    • url (blog url)
    • rss_feed (RSS feed for R-related posts. Ideally, you use "tags" or "categories" to identify your R-related posts. A title-based RSS feed is OK. If you need more input on how to get your RSS, have a look here)
    • photo_url (logo or profile)
    • language (one of ISO 639-1 Language Codes)
    • authors (list of authors)

Contributing details

All the blogs are listed in the blogs folder, where each blog is in its own json-file. These files are used to render a table on the upcoming revamped R-Ladies website. Follow the below instructions to add to the list. If you have any trouble, please create an issue for us to help.

Depending on how you are most comfortable working, there are several ways of adding new entries.

If you are not familiar with JSON you can open an issue with your blog info, which uses a GitHub Form, and we'd create the JSON for you!

Now we will focus on adding new entries directly through GitHub, but you could also work on a local copy (branch) or fork and add new entries that way too.

Create a new file

Create a new file in the blogs/ folder by using this link.

This link will fork the repository to your user account, and initiate a new file with some template content in it. After filling the file, please create a PR to the main branch.

File name

The name of the file should be the site url (without www or http(s):// . This way we can ensure each file has a unique name and that duplication does not happen.

File content

Using the link above will create a template for you to start with. Fill inn all the information that is relevant for your blog. There are several adaptations to an entry you can make that are not highlighted in every entry. Remove all mentions of \\required, these are just for making it clear which information you must provide for the file to be valid. Any optional field you don't want to add, you may delete entirely. For instance, if you don't have a subtitle or tagline for your blog, remove the entire line of "subtite": "subtitle or tagline" rather than leaving it empty with "subtite": ""

Photo

The photo url you provide will be displayed as your blogs thumbnail. This may be a picture of you, or if you have a logo for your blog/website, it may be best to use this in stead.

RSS Feed

Please add a content-specific feed in rss_feed. Ideally, you have a specific RSS feed for R-related posts. Depending on your website theme, the implementation may differ. We collected a few of the most common approaches below:

Quarto - Change the code in `index.qmd` as (under listing, also described [here](https://quarto.org/docs/websites/website-blog.html#rss-feed)): 
feed:
  categories: [R]
  • Note to new users that the category names will be the names of your category tags used in the blogs (not posts, which are the posts folder for Quarto blogs)
  • Then provide the RSS feed links as, [url]/blog/index-r.xml for R category posts ([url]/blog/index.xml will be the RSS feed link for main posts only)
Distill There is currently a [workaround](#54 (comment)) for adding RSS feeds in distill that works as follows:
  • In distill, there is a categories folder generated when a post is rendered which gets deleted when the blog is rendered
  • Store the folder and add it later because we need a categories folder, containing each specified category with an index.xml for each category
Hugo ###### Hugo Academic
  • Apparently the RSS feed is enabled by default and you can access it by using the field category in the YAML of your posts
  • Further readings for Hugo Academic
Hugo Portio
  • Copy and paste the content of this file (it’s Hugo’s default RSS settings)
  • Store it under layouts/_default/rss.xml (if there is no file, you need to create this one).
  • Exchange one line. Instead of <description>{{ .Summary | html }}</description>, we want <description>{{ .Content | html }}</description> (it’s at the very bottom of the file). This way, you RSS feed doesn’t show an excerpt but the full text.
  • More about Hugo Portio

If you want to check how your RSS looks like, you can use simple pie.

Authors

The entry may have several authors. This is for blogs where maybe there are several blogging together. If it is a blog that mainly has guest bloggers, its better to list the editors/maintainers of the blog and add "guest bloggers" as authors also.

Adding several authors means duplicating the content between the curlies {} in the author section, and adding a comma between each one.

"authors": [
  {
    "name": "Athanasia Mo  Mowinckel",
    "social_media": [{
      "twitter": "DrMowinckels",
      "github": "Athanasiamo"
    }]
  },
  {
    "name": "Mary Johnson",
    "social_media": [{
      "linkedin": "maryj",
      "youtube": "maryj"
    }]
  },
  {
    "name": "Guest bloggers"
  }
]

Icons

The social_media section supports many different key-value pairs. For rendering on the website, only the three first social media items for each author will be rendered.

"twitter": "username"
"mastodon": "@username@instance"
"bluesky": "username.domain"
"github": "username"
"instagram": "username"
"youtube": "username/end-url"
"tiktok": "username"
"periscope": "username"
"researchgate": "username"
"website": "url"
"linkedin": "username"
"facebook": "username"
"orcid": "member number"
"meetup": "end-url"

Language

The language field should be populated with the ISO 639-1 Language Codes of the site content. Please be thorough when entering this information.

Commit and PR the file

At the bottom of the page on GitHub, add a commit message in the box.

Propose changes

You will immediately be sent to the 'Pull requests' page, to create a PR to the main branch. Click the Create pull request button. Once this is done, a new page will open and some automated checks of your submitted entries start. In the comment section, make sure to @drmowinckels so she can take a look.

If anything needs fixing you will be notified and given instructions on how to do that.

Once all checks pass and the entries have been reviewed, they will be merged to the main branch.