Skip to content

Latest commit

聽

History

History
175 lines (119 loc) 路 9.36 KB

CONTRIBUTING.md

File metadata and controls

175 lines (119 loc) 路 9.36 KB
Raw

As a community, we welcome anyone to write and submit posts to the Unicorn Utterances blog! In this document, we'll go over how to create a new post in UU and submit it as a pull request.

Note

For a general tutorial on contributing to a project with GitHub, you may want to go through the First Contributions guide before continuing through this page.

Here are a few things to keep in mind while writing your post:

  • Be inclusive! We support all sorts of skill levels - don't disparage newcomers or discourage readers from learning new things.
  • Aim to provide factual and relevant information - citing sources is encouraged!
  • Keep your content unbiased; i.e. don't advertise commercial products or services without reason.

If at any point you get stuck or want to ask questions, feel free to open an issue on GitHub or reach out to us on Discord for help!

Contents:

  1. Creating an author profile
  2. Writing a new post
  3. Translating a Blog Post
  4. Submitting a Pull Request

Creating an author profile

Before creating a post, you'll need to add some information about yourself. To do this, create a new folder in content/ with your username, and add an index.md inside it; e.g. content/eric/index.md.

Here's an example of what your index.md might look like:

---
{
  // "name" should be your displayed name, however you want it
  // to appear on your posts
  name: "Eric Utterances",

  // "firstName" and "lastName" are unfortunately needed for
  // OpenGraph tags - fill these out however you feel is appropriate
  firstName: "Eric",
  lastName: "Utterances",

  // "description" is a short bio that will be shown on your profile page
  description: "Haskell programmer, fanfiction author, and an omniscient unicorn.",

  // Social usernames can include "twitter", "github", "gitlab",
  // "linkedIn", "twitch", "dribbble", "mastodon", "threads", "youtube",
  // and "cohost", as well as a "website" that can be anything you want!
  socials: {
    mastodon: "https://hachyderm.io/@UnicornUtterances",
    github: "unicorn-utterances",
    website: "https://unicorn-utterances.com/"
  },

  // "pronouns" are optional, but encouraged to include on your profile
  pronouns: "they/them",

  // "profileImg" should reference an image adjacent to this file
  // - ideally a PNG/JPEG of at least 512px resolution
  profileImg: "./profile.png",

  // "roles" should reflect how you contribute to the site - if you're
  // creating a post, this will just be "author", but there are more
  // roles for developers and translators as well!
  roles: ["author"]
}
---

Don't want to show your real picture on the site? That's alright! We have a myriad of custom unicorn emotes that can be used as profile pictures as well. They're adorable, go check! 馃ぉ

Once your profile is created, you'll be ready to proceed to the next step...

Writing a new post

All posts on Unicorn Utterances live in a content/{username}/posts/ folder - we structure this with a subfolder for each post, containing a markdown file named index.md. The naming of this post folder will match its URL on the site.

New to Markdown?

Check out the Markdown Cheatsheet for examples of how to format different types of content in this file!

When writing your post, you'll need to include some metadata in the frontmatter at the top of the file:

---
{
  title: "My First Post",
  description: "This is my first post on the Unicorn Utterances site!",
  published: '2023-04-11',
  tags: ["meta"],
  license: 'cc-by-4'
}
---

Hi! This is my first post! (TODO: write more text here)

Note: The "title" that you define here will always be displayed at the top of the post. You don't need to start your post with another heading - otherwise your post will have two titles!

Optional Properties

There are a few extra properties that you can specify in the post frontmatter, but are not required:

  • authors: ["author1", "author2"] can be used to manually specify the author IDs of a post, if written by multiple authors.
  • edited: "2023-10-21" can specify the "last updated" date of the post if any edits are made.
  • collection: "My Awesome Article Series" will treat a group of posts as a series if they all specify the same collection string.
  • order: 0 will reorder posts in a collection according to whatever value you provide. This has no effect unless the post is in a collection.
  • originalLink: "https://example.com" specifies an external URL that the post was originally sourced from. If you're reposting something you've written for another blog, this is important to provide!

Licenses

Providing a license helps to explain what readers can do with your work - whether that involves using it for course material, or reusing it in other forms. See the Creative Commons site for an overview of what permissions the various licenses allow.

Currently, the following creative commons licenses are supported as "license" values:

Authors may also choose to omit the "license" property entirely. If you do this, your post will fall under the repository's MPL 2.0 license.

Embedded Links

Blogs can embed their own <iframe> tags if necessary - these will initially show a "click to run" preview as to not affect the page's loading time.

A handful of third-party services can also be embedded by simply pasting the link in the post content, including YouTube videos, Twitch clips, Twitter posts - and anything supported by oembed.com.

Images & Videos

If you have linked images or videos, you'll need to save those files in the same folder and change your markdown file to reference them locally:

![Ferris, the adorable crustacean Rust mascot](./ferris.png)

Make sure to add descriptive alt text! Consider what information these images add your post, and what context might be important for readers with visual impairment.

Videos can also be embedded with the following syntax:

<video src="./ios_vs_android.mp4" title="A comparison of how text spacing is applied on iOS and Android"></video>

When possible, <video> elements should be preferred over .gif files or other animated images in our posts. This is for accessibility concerns - videos provide users with more control over when/how the animation plays.

Translating a Blog Post

If you are adding a translation, make sure to first create an Author Data File with the "translator" role so that you are credited for your work on the site!

To create a translation file for a post, copy its index.md file and rename it to index.(lang).md, where (lang) is the translated language. For example, a translation for fr (French) would be named index.fr.md. The content inside this file can then be translated into the respective language.

If any images used in the post need to be translated, these should be named in a similar fashion - for example, a translation of dom_tree.svg should be named dom_tree.fr.svg.

Any links to these images will need to be updated in the index.fr.md post to point to the translated image.

For reference, the current language codes can be found in /content/data/languages.json - you may need to add to this file if the language is missing.

Finding a Language Code

Each language code in /content/data/languages.json should consist of two lowercase letters. If it includes a region, append a hyphen followed by two more lowercase letters. For example, the code for French is fr - to specifically refer to the French dialect in Canada, the code would be fr-ca.

Please use - instead of _ in the language region ISO formats. Instead of fr_ca, it'd be fr-ca.

Refer to Wikipedia: List of ISO 639-1 codes for identifiers to be used in this format.

Submitting a Pull Request

Once all of your changes have been made, create a Pull Request to merge your post into the site.

  • Open a new Pull Request from your fork
  • Check that your files are in the Pull Request, and that they're being merged into the main branch.
  • Create the PR and wait for a maintainer to review it.
  • Once merged, your post will be visible on the site!

We'll get in touch with any questions or feedback once we've reviewed your post!