Video playlist explaining the upload instructions. Please follow along with the guide below.
Prerequisites:
- Github account
- Text editor, such as Visual Studio Code, Sublime Text, Atom
- Prepared markdown (.md) file. (Note: All articles must be submitted in properly-formatted markdown). See Github Markdown guide.
In order to upload your prepared .md file to Github, first, click the Fork option in the upper right-hand corner (pictured below).
Once you have successfully forked over to your repository:
- You should notice your username in the upper left-hand corner (top red arrow).
- If a Github Action notice pops up, click Dismiss (red arrow in the middle).
General rules: Students should always be branching from their master
Students should always keep their fork up to date with section-io/engineering-education
Next, you will need to clone the repository to your local computer.
Open the newly cloned repository in your text editor. It should look something like this (shown in Visual Studio Code):
Note: When working with multiple articles simultaneously, it's best to create and work on separate branches for each article. (Here is a short video on how Github Branches work.)
Within the articles folder (inside the content folder), create a new folder using the intended url for the article. (Reference existing folders' naming conventions.)
Be sure to:
- Use all lowercase.
- Use dashes in place of spaces.
- Do not include any special characters.
- Try to keep it under 40 characters.
- -Avoid using periods (.) or commas (,) or (_ ) underscores
Within that article folder, upload your prepared .md file containing article contents using the filename index.md. Upload any corresponding image files referenced in your article. When referencing images, be sure to use the following naming convention with your newly created article directory.
For example:
If you have a header (hero) image in mind, feel free to include it your PR as well. Please try to keep images as close to 600X400 pixels (images can be resized using Pixlr Image Editor) and make sure you have the appropriate copyright to use it. Sites like Unsplash have Creative Commons images which you can use for free.
Any images within the article need to be hosted on our site - (place the image in the proper folder) - and have the proper image paths in the article similar to the hero image and have citations (attribution) if required.
Your folder should look similar to this:
Once your files are properly uploaded and organized, add, commit, and push your changes to your forked remote Github repository either using the command line or the Github tools within your text editor.
We recommend running the development server locally to test your changes before submitting a pull request. Follow the instructions below to run the development server.
Prerequisites
- Install hugo v0.101.0_extended for your operating system.
- In the terminal navigate to your project directory.
- Start up the development server by running the command
hugo server -D. - Navigate to
http://localhost:1313in your browser.
Open Github. You should see a message indicating your pushed changes with a button to 'Compare & pull request'.
Open a pull request that includes the name of your article and a description of the contents that you are submitting.
Note: Make sure your repository is up to date with the EngEd repository before contributing new articles.
git remote add section http://github.com/section-io/engineering-education
git fetch section
git pull --rebase section master
git push originHere is a link to a short video further explaining what a pull request is and how to fork a Github repository.
Before submitting your article make sure you take advantage of this useful tool, Hemingway that helps with word count, formatting, and grammar/readability.
By highlighting lengthy, complex sentences and common errors, it helps make any writing BOLD & CLEAR. If you see a yellow sentence, you may want to shorten or split it. Please use on all future articles before submitting a PR (pull request).
To review your Code Snippets or examples before submitting, take full advantage of the free online tool, repl.it. Use it to run and compile any code snippets to be included in your article.
If you would like to include a (step-by-step) video to one of your How To Guide or Tutorial videos feel free to do so as a YouTube iframe. Below is a step by step example on how to include a YT iframe to your .md files.
Upload the video to YouTube (if it isn't already).
Take that copied embed code and paste it into your .md (markdown) file where you would like it to be placed. The code should look something like this:
<iframe width="956" height="538" src="https://www.youtube.com/embed/npnp--SSx_8" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
NOTE: If the width and height are not width="478" height="269" be sure to change the sizes to fit our web page format.
Congratulations! Your article is now ready to be submitted for review and approval by the Section team. Open a pull request and we'll be happy to review it.
After you have published your article with us - be sure to check on your content periodically to respond to any comments or questions that the audience may post. Please sign up with HyvorTalk to reply to any comments or questions left on your articles.