Contributing Guide

Detailed Guide

This guide will help you learn how to add formatted resources to our website!

Visit the resources repo

Visit Repo

Fork the repo

This step is for those contributors who do not have team member access to the repository.

A fork is a duplicate of the original repository where you can make changes without affecting the source project.

Click on the fork button.

Select your namespace and hit Fork Project

Create a new branch

The name of the branch should be in lower-kabab-case. Try to keep it precise and to the point.

We've named our branch example, but you could try ai-resources or updating-queue.

After naming your branch, click Create branch

Start Editing

To get started with editing your copy of the resources repo, you can either clone it locally or open it in Gitpod.

Gitpod

Before launching Gitpod, make sure you are in the same branch as you have created earlier.

We will be using Gitpod for the rest of this tutorial, but the steps for developing on Gitpod or your local copy of the repo should be the same. Gitpod provides you with a VS Code-powered IDE for any Gitlab or Github repo.

Local Development

git clone https://gitlab.com/grey-software/resources.git
cd resources

Web IDE

If you're making a simple addition to the queue, you don't need to run a live preview to ensure your changes are correctly formatted.

Simply open the queue file in the Web IDE, and you'll find it much easier to submit your edits without leaving Gitlab.

Install Project Dependencies

After launching Gitpod, type yarn to install the project's dependencies.

yarn

Start Developing

Then type yarn dev to start a local server that will allow you to see your development changes.

yarn dev

Answer `y` or `n` to whether or not you'd like to contribute your data to improve the NuxtJS developer experience. We usually answer `y`

Open a preview browser

Select Open Browser to preview your changes to the website in another tab.

Its OK to allow popups from gitpod if your browser prompts you

Edit a Resource Page(s)

On the left side of the Gitpod IDE, you'll find the project file explorer, through which you can navigate to the content folder, where you'll find the Markdown files that contain the content for our resources website's pages.

Each category has several pages. We will leave it up to you to explore them and decide where you want to share your knowledge.

You have few options here

The page you want to add to already exists.

Please proceed to the next step Add YAML Metadata.

You need to create a new page

Right-click on your category's folder, and hit New File.
Name the file in lower-case with no spaces, only hyphens, and with the Markdown .md extension .e.g computer-science.md

You need to create a new category.

Right-click on en and select the New Folder option.
Name the folder in lower-case with hyphens instead of spaces.
To create a page in the same category, follow these two steps.
- Right-click on your category's folder, and hit New File.
- Name the file in lower-case with no spaces, only hyphens, and with the Markdown .md extension .e.g computer-science.md

Add YAML Metadata

If you're adding resources to a page that already exists, then you don't have to add the title, description, and position metadata to the YAML frontmatter in the page.

However, for a New Page, you need to add the following metadata.

- title: _name of the page_
- description: We're compiling a library of useful **\_\_\_** from around the Internet to help you on your software journey!
- position: _position of the page_
- category: _name of the category_

Format with Markdown & components

For video link, we use YoutubeVideo.vue component to embed Youtube videos so that they remain responsive!

<youtube-video id="Ag1AKIl_2GM"> </youtube-video>

We use the CtaButton.vue component to draw users to important links.

<cta-button text="CTA Button" link="https://grey.software"></cta-button>

CTA Button

Submit your changes

After writing all the content, click on the version control button. It will show you the number of changes you have made and allow you to submit your changes.