Our Standards

You want to help with this site and contribute? That’s awesome! Let’s get started with some basics.

Our standards remain the same or similar when you read the announcements section of the Staff Guidelines. To point things out, the important parts of the Staff Guidelines will be listed here and adjusted for ease of use.

Tone of Delivery

• Posts must be neutral to the reader. No bias should show or any favoring to specific topics. Only on rare occasions should this rule be voided.
• Grammar and styling should be consistent with previous documents. When creating or editing a copy, please check grammar with built-in text editors.
• Documents must be easy to digest and understandable for readers. Be sure to avoid any complex or abrupt sentences. If you see a problem with a document, remember “Edit This Page!” is there for you to use!

Keeping Consistency

• All posts are to be written in United States English. Different spellings for different words will occur, so be mindful of spelling. Terms including but not limited to are: color, center, skillful, analyze, etc.
• Documents must follow RFC 2119. It is also encouraged to use proper markdown for writing.
• Trademarks must be correctly typed, including games, media, music, etc. Examples include YouTube, Discord, etc.

Articles and Posts

This website is using Jekyll! Jekyll is a static website generator. It allows for content to be displayed readily on the site. One of the most significant things Jekyll offers is Markdown. Markdown is a markup language that describes how text should appear on a page.¹ If you need a quick overview of Markdown, please look over this Markdown Guide to get the gist of it.

In theory, it should be effortless to contribute to articles and posts like the one you’re looking at now. Each editable page has a link saying “Edit This Page!” meaning you could go ahead and edit the Markdown contents of the page.

When users click “Edit This Page!”, they are sent to the website’s Content Management System (CMS), where they can edit the Markdown contents easily. Users who found their way into the CMS must also login using GitHub. GitHub will allow the user to create Pull Requests, commits, and more! Everything is done automatically in the CMS, so the average person only needs to worry about writing standards.

Creating Documents

This is for people not using the CMS and are wishing to dig into the files/codebase.

Documents are prefered to be created using Jekyll::Compose. To use Jekyll Compose, you must type bundle exec jekyll post "My New Post". This will automatically create a document for you in the _posts folder. Once this is handled, documents must be moved to their respective folder in ordered to be displayed correctly. There are a few benefits to this, including automatically generating the front matter for you!

Displaying Documents

It’s required to create a document within a dedicated folder. The main folders are postsBlog, postsNews, postsWiki, postsInclude.

Documents in postsBlog, postsNews, and postsWiki will display in the homepage clearly. Documents in postsInclude will be displayed as an “included post” under a specified wiki post. More on that later.

Each document must contain “front matter” to display content properly on the site.² Front matter is the metadata and settings of a document. Every document should have the layouts of article or post. Articles display the Table of Contents wedge to the left while posts do not have a Table of Contents wedge.

Every document’s main front matter elements are layout, title, date, category, author, and description. An example for this is shown below.

---
layout: article
title: Camellia
date: 2023-12-10 13:35 -0600
category: pages
author: JoshuaGreatXD
description: The one and only Camellia! Here, you can find information about Camellia's background and accomplishments.
---

Linking Wiki Posts and Included Posts

When a document is included in a Wiki Post, it will not show up on the homepage clearly. Instead, it will be shown under the Wiki Post as shown below. This is known as an Included Post.

To add an Included Post within a Wiki Post, you must add include: (Included Post Title) in the Wiki Posts’s front matter. Once done, it will be displayed in the wiki posts’ card, just like magic!

Markdown example of using include in the front matter.

---
layout: article
title: Song Use
date: 2024-01-09 00:43 -0600
category: pages
author: shiosama
description: Camellia's Music Usage Guidelines. Where you can find information about how and when to use his music!
include: Song Use (Official)
---

When to use different Layouts

While the Article and Post layouts are similar, they function differently. Articles are supposed to be used only when the document content is very long and there are different sections. Article layouts have features such as content wedges and IDs applied to headers.

Posts are meant for smaller bits of information that usually don’t have a scrollbar. This includes quick, small messages, news posts, and blog posts.

Styles

Custom classes and styles could still be applied in the CMS editor. Though, the editor will not display them correctly due to limitations we haven’t solved yet. Keep this in mind!

While this site has markdown support, it also has a extended version of markdown called kramdown. Kramdown is a library for parsing and converting superset of Markdown.³ Essentially, kramdown is the same as markdown but expanded.

Kramdown offers adding classes for CSS or IDs to specific parts of a document. Examples will be listed below.

Codeblocks

If you’re familar with Discord’s markdown then you should reconize this.

\```ruby
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')

# => prints 'Hi, Tom' to STDOUT
\```

By removing the backslashes and specifying the programming language, it would be correctly displayed as a code block. To review more on this, visit the kramdown cheat sheet here.

Blockquotes

Blockquotes are preferred to be only used in articles, they function as a way to give a “heads up” to the reader. Examples for default blockquotes and styles will be listed below.

This is a default blockquote.

This is a disclaimer blockquote.

This is a caution blockquote.

This is a tip blockquote.

To use blockquotes, you must type a > before a sentence. To apply different attributes (classes), you must type the attribute and class name {: (class/ID name)}.

To give you an example of what blockquotes should look like in markdown, it will be listed below.

> This is a default blockquote

> This is a disclaimer blockquote.
{: .disclaimer }

> This is a caution blockquote.
{: .caution }

> This is a tip blockquote.
{: .tip }

To learn more about blockquotes, please visit the kramdown cheat sheet here.

Code Contribution

When contributing, you may need to familiarize yourself with GitHub and git. GitHub is made for merging and collaborating code between developers. It helps maintain this website and allows us to add to it easily.

You could skip this section if you want to get into profound contributions such as Sassy CSS, JavaScript, and HTML.

Here are some crucial parts of the readme you must remember when contributing code.

You must install Jekyll

To install Jekyll, please refer to the Jekyll Installation page.

Please never edit the CSS files

Because this project uses Sass (Sassy CSS), it will automatically convert your styling to the proper CSS files. Please be sure to install the .scss extension! To learn how to use Sass here. To install Sass with NodeJS, please run: npm install -g sass.

Testing Locally

If you want to test locally, please follow these steps:

1. Install Git and Jekyll (if you are contributing to styling, install Sass)
2. Open your terminal of choice
3. Clone the repo with git clone https://github.com/CamelliaCommunity/Wiki
4. Go inside the newly created folder with the clone
5. Run bundle install to install the gems required
6. Run bundle exec jekyll serve to run the local server
7. Enter the URL it provides (like http://localhost:4000/) in your browser to view your local copy Please refer to the Jekyll Docs if you are still unsure!

Pull Request Tip

Congratulations that you made it this far! Now that you’ve understood everything (in theory), it’s time to create a pull request in the GitHub! When creating a pull request, you must fork the respository. Please make sure you forked the beta branch instead of the live branch. If you click the “Edit This Page!” button, GitHub will show you a screen about forking the repository. This method is an easier way to create a fork and is preferred for first-time contributors.

Once the repository is forked and its contents are edited, create a pull request that merges items into the beta branch. NEVER create a pull request to merge in the live branch. If you do that, you should feel bad.

This is it for contribution. Almost all articles and posts are editable for the user. If you see ways to improve documents, don’t hesitate to contribute!

References