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 repository (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 documentation.
Once you've created something you want to share with a friend, student, or collaborator, you'll want to save the sketch. To do this, use the save shortcut (ctrl + s or cmd + s on Mac). Using this shortcut saves the code currently in the editor into netnet's local session data.
For more information on netnet's local session Data Privacy
When the local sketch is saved, netnet will also give you the option to "share" this sketch. To do so you will need to 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.
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.
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.
➡️ Note: 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 one step which is named "getting started" by default. You can change this by editing the content in the step title field and pressing the update this step button. New steps/annotations can be added by clicking the add new step button or removed by clicking the remove this step button (:warning: WARNING, there is NO "undo").
| 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.studio repo as explained in the first step of our tutorial on 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 means, not only are you downloading the code from your repo, but also a hidden directory called .git which contains the git metadata that includes 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 these files directly, the
gitcommands 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. However, 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.
➡️ Helpful Tip: You can run git ---version to check if you already have git installed.
Now that you have git, to clone your fork you'll need to open a terminal on your computer.
On Mac you can use "spotlight" (the Mac search box) and search 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 folder 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.
Next, 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.
If you'd like to include this example in one of our "curated lists", you can optionally 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 lists, each contains the list's name as well as an array of id values of the example which should appear in that list. Add your example's id to the array belonging to the list 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. To do this, first you must add 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 as demonstrated below. 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
➡️ Helpful Tip: if this is your first time pushing code from your computer to your GitHub account you'll need to make sure you have your credentials setup property. There are a few ways to do this, one way is to run our npm run setup script to launch netnet's guided local development setup, which includes a step to enter you personal access token.
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 appropriate branch of your forked repo (the right side) into the main branch of the our 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!
For more information on pull requests click here!
If you want to help work on our widgets, by either editing an existing one or creating a new one, check out the "edit/create a netnet widget" docs.
If you want to make another kind of contribution refer to our contributors guide to learn how to dive even deeper into the repo!