code examples
If you'd like to create a new netnet sketch or an annotated demo/example or fix a bug a pre-existing one, then you're in the right place! Below you'll find documentation for how to create and share a sketch on netnet, how to annotate a sketch as well as how contribute your annotated sketch as an interactive example on netnet.studio...
- "fork" the repo (if you haven't already)
- make sure you have "git" installed "locally"
- "clone" your fork to download the repo locally
- add your annotated sketch to the repo as a new "example"
- "commit" and "push" your example
- create a "pull request"
The quickest way to start working on an interactive code example is to go straight to netnet's editor: https://netnet.studio/#sketch and start writing (or copy+paste) some code. The editor includes your standard code editor features as well some special ones designed for creatives learning to code for the first time, you can learn all about these features in our Sketching doc.
Once you've created something you want to share with a friend, student or collaborator use the save shortcut (ctrl + s or cmd + s on Mac). Using this shortcuts saves the code currently in the editor into netnet's local session data (see Data Privacy for more on that), but netnet will also give you the option to "share" this sketch, choose the "Can I share this sketch?" option and netnet will open the "Share Widget" which you can use to create a shareable URL that you can copy+paste anywhere. This URL contains a compressed version of the code itself (see Anatomy of a netnet URL for more info on that), this way examples/sketches can be shared with others without the need to create accounts or store any data on our servers (unless you choose to shorten the URL, which can be helpful especially to generate a QR code you can use to quickly test your sketch on a mobile phone).
Sharing sketches with students and collaborators via netnet is great because not only can it be used to quickly ping-pong remixes back and forth, you can also take full advantage of all of netnet's helpful features, like friendly error messages and double-clicking any piece of code to have netnet explain it to you.
Developers have been annotating their code with "comments" for years, but if you're an educator looking to annotate interactive code examples in a more beginner friendly way you can use our Demo/Example Maker widget. This widget let's you annotate your sketch and create a special link where netnet is used to explain the code in its editor step by step.
Here's a simple example of what an annotated sketch looks like.
Because annotations, which show up as netnet dialogue, are written in HTML which means they can be styled and include links (both to external sites and internal netnet references) as demonstrated in the example linked above. In that example you'll also notice netnet can highlight specific lines in the editor to draw attention to them at any particular step/annotation. Additionally, you can choose which layout you'd prefer netnet to be in when you share the example as well as whether or not to include an optional "table of contents" widget with your example which lists each of the annotations or "steps" (these can also be accessed by clicking the green dots next to the line numbers in the editor if/when the table of contents isn't present)
To create these, navigate to https://netnet.studio/sketch to get started with a new sketch and then open the Demo/Example Maker widget with the ctrl + 4 (cmd + 4 on Mac) shortcut key. You can also use that shortcut to open the widget on a pre-existing example to edit those annotations.
The Demo/Example Maker widget contains a drop down list of "steps" (or annotations). An annotated sketch needs at least 1 step which is named "getting started" by default, but you can change this by editing the content in the step title field and pressing the update this step button. New steps/annotaitons can be added by clicking the add new step button or removed by clicking the remove this step button (warning, there is no "undo"). Each step contains three fields...
| field | explanation |
|---|---|
| step title | this title appears in the Code Example widget's Table Of Contents, these can be clicked to jump to that annotation |
| line numbers | You can optionally choose to have netnet focus on (spotlight) a particular section of your code by specifying the line numbers (comma separated) of the code you'd like to highlight |
| explain step | The text you type into this field is the content that will show up in netnet's speech bubble. This can include HTML code (like <code>, <b>, <i> and <a> elements) |
To share your annotated code example with someone simply press the generate link button and then click on the generated link to copy it. The URL itself contains not only your compressed code but also all the annotation data.
If you'd like to contribute the example you made to our project so that it appears in netnet's Code Examples widget publicly for everyone to learn from that would be amazing!
Assuming you've forked the netnet.stuio repo as explained in the first step of our tutorial for how to edit some of netnet's dialogue, you'll be able to "clone" your fork down from your GitHub account and onto your computer. "Cloning" a repository mean not only tha you're downloading the code from your repo, but also a hidden directory called .git which contains the git metadata, including the history of changes made to our code thus far. NOTE: as the name implies a "hidden directory" is a folder in your project that you can't see by default, but most systems (Windows, Mac, Linux) have shortcut keys you can press to display these hidden folders if you're curious. They're hidden for a reason, we're not really supposed to interact with thes files directly, the git commands we run in our terminal do that for us.
When you use GitHub online, behind the scenes the website is using a command line tool (or terminal application) called git to keep track of changes to our code. But because we're going to be cloning our code and making a "local" copy of our repository on our computer, you'll first need install git if you haven't done so already.
Assuming you have git installed, to clone your fork you'll need to open a terminal on your computer. On Mac you can use "spotlight" (the Mac search box) for "terminal", on Windows you can search for "Git Bash" (alternately you might also be able to use the terminal for Window's Linux Subsytem if you prefer). When you open up a new terminal, it's usually open to your home foldre by default, we'll need to use the cd command to "change directories" (or switch folders) into whichever directory you want to clone (or download) the repo to. You can do this by running cd /path/to/folder or simply typing cd followed by a space and then drag and dropping the folder into the terminal to automatically enter the path to that folder. After hitting enter you should now be in that directory.
To clone your repo into your current directory type git clone YOUR_FORKED_URL and press enter (replacing "YOUR_FORKED_URL" with the URL to your repo). You should then see the git command begin downloading your code, when it finishes you should notice a new folder called "netnet.studio" appear in that directory.
Back on netnet, you can use the Demo/Example Maker widget to give your demo a name, then instead of clicking generate link you'll click on download json to download the example data you've created as a .json file. Place that file into the "examples" folder, which is in the "data" folder of the repo (the new "netnet.studio" folder you cloned), ie. the /netnet.studio/data/examples/ directory.
Even though your example is now in the repo, it won't be discoverable by the user. The example will not appear in netnet's Code Examples widget until you specify which section it should appear in. To do so you'll need to edit the examples-map.json file which is also in the "data" folder, /netnet.studio/data/examples-map.json. This file contains a list of example sections, each contains the section's name as well as an array of id values of the example which should appear in that section. Add your example's id to the list belonging to the section you'd like to add your example to. Your example's id value is the number found both at the start of the downloaded json file's name as well as in the json file itself (in the key value).
Once you've added the .json to the /netnet.studio/data/examples/ directory and updated the /netnet.studio/data/examples-map.json file it's time to commit your change. Open a terminal and navigate into the repo's directory by entering:
cd PATH/TO/THE/REPO
Replace "PATH/TO/THE/REPO" with the file path to your cloned netnet.studio repository. Don't forget that you can simply type cd followed by a space and then drag and drop the folder into the terminal to automatically enter the path to that folder. After hitting enter you should now be in that directory.
Once your terminal's pwd (present working directory) is set to the netnet repo, you can create commit, first by adding the files you would like included in this commit to the stage and then by committing those changes. You can add every new/changed file to the stage by entering git add . or you can add both files individually by entering:
git add data/examples-map.json
git add data/examples/YOUR-DEMO-FILENAME.json
Optionally, you can confirm that you've added the correct files to the stage by running git status. Once your stage is set commit it. Between the quotes, where it says "YOUR MESSAGE HERE", leave a brief comment explaining the demo/example you created:
git commit -m "YOUR MESSAGE HERE"
Lastly, push your committed changes back up to your "remote" repo on your GitHub account by entering:
git push
Once you've edited and committed a change to your forked repo it's now time to make that an official contribution to netnet.studio by opening up a "pull request"! A pull request or "PR" is how you let us know that you've made an edit you think we should include in our repo.
Navigate to the Pull Request (PR) tab on either our repo's page or your forked repo's page. Click on the green "New pull request"
Make sure the request is going from the main branch of your form (the right side) into the main branch of the class repo (the left side). The arrow icon between the two conveys the direction of the pull request. NOTE: If you don't see all the drop-down menus shown in the image below, you may first need to click on the "compare across forks" link.
The PR should automatically name this new request after the commit message you left, but if not make sure to give the pull request a name/title that generally explains any/all of the edits you made.
Once the PR has been opened a page is created in the PR tab where a conversation about your contribution can take place. GitHub's PRs not only allow us to leave comments/feedback discussing your edits, but also enables us to reference specific lines of code from within the files you edited (like pull quotes). If we notice anything that needs addressing or changing before your contribution can be merged with our repo, we can start a "review" where we'll point out specific mistakes you might have made or changes we'd like you to consider.
If we do give you some feedback or request some changes, the PR will remain open and any future commits you make will automatically be registered in the PR page. Once everything looks good we'll "accept the pull request" which will "merge" your changes with our repo. Congrats you're now an official/credited contributor to netnet.studio forever a part of the repository's git history!
If you want to make another contribution refer to our [contributors guide][contributors-guide.md] to learn how to dive even deeper into the repo!