How to contribute to DDRGuide (for beginners)

This guide explains how to set up DDRGuide for local development on a Windows 10 machine, make changes to the site's content, and perform basic Git(Hub) operations.

Getting started on GitHub

These steps are only necessary if you want to change DDRGuide and submit your changes for review.

1. Create an account on GitHub. In the following steps, replace "yourname" with the GitHub username you chose.

2. On the main page for DDRGuide, press the Fork button to create your own copy of the repository. You should be redirected to a new repository labeled "yourname / ddrguide".

Setting up your development environment

1. Download and install the following software:

• Visual Studio Code (aka VS Code)
• Git
  • When prompted to choose a text editor, change the default "Use Vim (the ubiquitous text editor)..." to "Use Visual Studio Code...", or another text editor if you have a preference.
  • All other default installer settings are OK, but you can opt out of the Start Menu / Desktop shortcuts, Windows Explorer integration, and file associations if desired.
  • Don't choose "Use Git from Git Bash only" when offered, otherwise VS Code won't recognize that Git is installed.
• Node
  • Make sure "Automatically install the necessary tools" is checked when offered. This will open a separate install terminal after Node finishes installing.

2. Type cmd into the Start Menu search, then choose "Run as administrator" and issue the following command:

npm install --global windows-build-tools

• Note that installation has not finished until you see "All done!" in the terminal. If it seems stuck, try pressing any key in the terminal window.

3. Open VS Code and choose "clone repository..." from the Welcome screen. Choose "GitHub" from the dropdown when offered, then allow the GitHub extension to sign in. You may need to click various "Allow" and "Open" buttons along the way.

4. Once you're back at the "Repository name (type to search)" prompt, choose "yourname/ddrguide" (or search for it if it doesn't automatically appear), then pick any folder to store the repository. VS Code should now have the "ddrguide" folder opened.

5. Open a new terminal with Ctrl-Shift-` or Terminal > New Terminal; the prompt should end with ddrguide if all went well in the previous step. Issue the following command:

npm install

• This will install everything you need to build & run DDRGuide as a local web server on your computer; expect it to take a few minutes.
• If you get any errors, double-check that the command from Step 2 succeeded, then restart VS Code and try running npm install again.

Running DDRGuide

In a VS Code terminal, issue the following command:

npm run start

As long as this command is running successfully, you should be able to view DDRGuide at http://localhost:3000/ in your web browser. You can stop the local server by typing Ctrl-C into the terminal, then Y+<Enter> to confirm. For quick restarting, you can press the <Up> key in the terminal to restore the last command, then <Enter> to run it again.

How content is stored

Most of DDRGuide's content is stored under the content/ folder of the repository. Resources like the glossary are stored in YAML (.yml) files, while articles are stored in Markdown (.md) files. Both kinds of files can be edited directly through VS Code.

All text formatting is done through Markdown, the same markup language used by Discord. However, DDRGuide parses links differently:

• To link to an article from another article, or a glossary entry from another entry, put the glossary term or article slug in [brackets].
  • Capitalization doesn't matter.
  • An article's "slug" can be found at the top of its .md file, and your link can replace the dashes - with spaces.
• To link to a glossary entry from an article, put glossary: after the opening bracket.
  • This works in reverse too (using article: instead), but no glossary entry links to an article currently, so this functionality isn't tested.
  • Some links use a song: prefix that currently takes you to a placeholder page. They're useless for now, but maybe they'll do something in the future.
• To change the link's displayed text, put the text you want to show before the glossary term or article slug, separated by a |.
• To link to an external website, use the | separator as described above and put the URL after the |.

Take this sentence from the "Deciding what to play" article for example:

Use different [glossary:categories|category] to narrow down your search for songs to play.

This links to the glossary entry for "category", but displays the word "categories" for grammatical clarity. If this sentence appeared in the glossary, the glossary: prefix wouldn't be necessary - you could write [categories|category] to achieve the same effect.

External link example: [DDRCommunity.com|http://ddrcommunity.com/] displays the text "DDRCommunity.com" and links to the URL after the |. The URL must start with http or https, otherwise it won't parse correctly.

You can find more formatting examples by looking through the existing content.

Editing the content

If you make any changes under the content/ folder and you want to see them on your local site, you'll need to either:

• execute npm run content-to-json in a new VS Code terminal, or
• restart the npm run start command as explained above.

You don't need to do both, as npm run start automatically runs the content-to-json script.

Adding a new article

Adding new articles is unfortunately a clumsy process currently. You'll want to create a new .md file under content/articles/, then:

• add your new article's slug to the articles array at the top of tasks\content-to-json.js
• re-run the content-to-json script as described above
• add a new import declaration for your article in src\components\Article\Article.tsx below the existing ones, like this:

  import decidingWhatToPlay from  '../../content/articles/deciding-what-to-play.json';
  import homeSetupAndResources from  '../../content/articles/home-setup-and-resources.json';
+ import myCoolNewArticle from '../../content/articles/my-cool-new-article.json';

• find the allArticles array in the same file and add your new import to the end, like this:

- allArticles: ArticleContent[] = [navigatingTheDDRUI, ..., homeSetupAndResources];
+ allArticles: ArticleContent[] = [navigatingTheDDRUI, ..., homeSetupAndResources, myCoolNewArticle];

Article images are stored under public/images/. There are two special image files associated with each article:

public\images\Article - Header - my-cool-new-article.jpg
public\images\Article - Thumbnail - my-cool-new-article.jpg

These are the header and thumbnail for your cool new article. They must have that exact filename (but with the real article slug, of course) and must be JPEG images.

For supplementary images, the filenames typically look like Article - my-cool-new-article - Image Description.jpg. You can embed them from your article with a special !-prefixed link. For example:

![Premium Play|/images/Article - navigating-the-ddr-ui - Premium Play.jpg]

• The text before the | is the image's alt text and should provide a succinct description of the image for visually impaired readers.
• Note that the image path starts with /images/, not /public/images/.

Sending your edits in a pull request

Let's say you've made some changes in VS Code to your copy of DDRGuide and you're happy with how it looks.

1. Switch to the Source Control sidebar on the left - it should have a badge indicating how many files you've changed.

2. In the "Message" textbox, write a commit message describing what you've changed, then press Ctrl-Enter to commit your change.

• When told "There are no staged files to commit", choose "Always" to always commit all changes.
• This step commits your changes to your computer's copy of your repository.

3. From the "⋯" menu in the Source Control tab, choose "Push" to upload your changes.

• This step publishes your changes to your repository that you forked on GitHub.

4. Create a pull request on GitHub. For now, refer to GitHub's documentation for this step.