Food Stories Editing and Submitting Guide

This guide is useful ONLY AFTER you have followed the directions for setting up your repository and starting your page.

Reminder! Create bookmarks for two locations you will be visiting often:

• YOUR own Food Stories REPOSITORY: https://github.com/USERNAME/food-stories/
  • Replace USERNAME with your GitHub username!
• YOUR own Food Stories WEBSITE: https://USERNAME.github.io/food-stories

Editing your new page

Replace content on the sample page

Now that you have a working website and your own page to edit, you’re ready to replace all the sample content with your own.

It’s best to write out anything you want on your page in Word or whatever and then copy and paste it into GitHub when you’re editing your page. Editing in the tiny GitHub text edit box is annoying and it’s too easy to miss typos and other mistakes.

Once you have replaced the sample text with your own, click the green Commit changes... button.

Upload Your Audio File to GitHub

1. Go to your GitHub repository in your web browser
2. Navigate to YOUR story folder by clicking on it (the two samples are in bbq and casserole)
3. Click the Add file button (upper right)
4. Select Upload files
5. Drag your audio file into the upload area or click to browse
6. Scroll down and click Commit changes (you can leave the default commit message)

Upload Your Image File to GitHub

1. Go to your GitHub repository in your web browser
2. Navigate to YOUR story folder by clicking on it (the two samples are in bbq and casserole)
3. Click the Add file button (upper right)
4. Select Upload files
5. Drag your image file into the upload area or click to browse
6. Scroll down and click Commit changes

Edit your page to use the new files

Your food story page uses two special “include” codes to display your audio recording and image. You need to update these codes to match the files you uploaded.

• Find this line on your page: {% include audio.html src="bbq.mp3" %}
• Change the bbq.mp3 to whatever YOUR audio file ism names
• Be sure to keep the quotes, and make sure what’s between the quotes is EXACTLY the same as the name of the file you uploaded.

Do the SAME THING for your image

• Find this line on your page: {% include figure.html image-path="bbq.png" caption="Your caption here" %}
• Change what’s between the quotes for the image-path to be your image filename.
• Be sure to keep the quotes, and make sure what’s between the quotes is EXACTLY the same as the name of the file you uploaded.

Commit your changes! Use the green Commit Changes button as usual to save your work.

Verify Everything Works

After uploading both files and updating code snippets with your filenames (and committing your changes):

1. Wait 1-2 minutes for GitHub Pages to rebuild your site
2. Visit your food story page on your website (you bookmarked it, right?)
3. Check that:
   • Your audio player appears and plays your recording
   • Your image displays correctly
   • The caption shows properly

Troubleshooting

Audio or image doesn’t appear?

• Make sure you didn’t accidentally remove or add extra code characters, like {% or %}
• Make sure you’re not missing any quotation marks
• Double-check that the file names in your code exactly match the uploaded file names (including capitalization and file extension)
• Wait a few minutes and refresh your browser—GitHub Pages can take time to update

Audio player shows but won’t play?

• Check that your audio file is in a supported format (MP3 works best for web browsers)
• Make sure the file uploaded completely and is in the correct place

Image is too large or too small?

• You can add width="50%" to the figure include to control size:

Submitting your Essay

Double check everything is done

Be sure you’ve followed the guidelines and have all the expected components (brief intro, image, functioning audio player, analysis).

Pull Requests

When you are completely done editing, you need to get your local changes (in YOUR repository) to the main Food Stories site that everyone sees. Basically, you want me as the site manager to “pull” your changes from your remote repository (your copy of it) to the main site. In GitHub speak, this is called making a pull request. If you have followed the assignment instructions, I will “accept” the request; if not I will “reject” them. This process prevents mistakes, bugs, and crappy pages from showing up on the main site. You will still get credit for your assignment regardless.

How to create a pull request

• Go to the homepage of YOUR Food Stories repository, and click the Pull Request nav link near the top.
• Click the Green New Pull Request button.
• GitHub will show you what changes you are making, line by line (a whole paragraph counts as a line). Verify that the changes are correct. You should see where you replaced the sample text and changed the names of the audio and image files.
• Click the Green Create Pull Request button.
• You should see near the top a green message that says Able to merge. If you don’t see that, you should just stop and send me an email.
• Click the Green Create Pull Request button.

You’re done!

After you make the pull request, there’s nothing else to do! If you notice that you missed a typo or something you can always make another change and another pull request. Thank you for all of your hard work to launch our new food archive! Once all the pull requests are approved, you should be able to see and listen to all the stories at the Food Stories Archive.