-
Notifications
You must be signed in to change notification settings - Fork 36
Expand file tree
/
Copy pathindex.html
More file actions
285 lines (177 loc) · 17.9 KB
/
index.html
File metadata and controls
285 lines (177 loc) · 17.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
<!DOCTYPE html>
<html>
<head>
<!-- Meta -->
<title>Nutshell: make expandable, embeddable explanations</title>
<meta content="text/html;charset=utf-8" http-equiv="Content-Type">
<meta content="utf-8" http-equiv="encoding">
<meta name="viewport" content="width=600"> <!-- mobile -->
<!-- Favicon -->
<link rel="icon" type="image/png" href="favicon.png"/>
<!-- Shtuff for this indexpage -->
<link rel="stylesheet" href="indexpage/index.css"></link>
<script src="indexpage/index.js"></script>
<!-- Nutshell, as promised! -->
<script src="nutshell.js"></script>
<script>
/*Nutshell.setOptions({
lang: 'ru', // Language (default: 'en', which is English)
});*/
</script>
<!-- Social sharing -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@digitalocean" />
<meta name="twitter:title" content="Nutshell: make expandable, embeddable explanations" />
<meta name="twitter:description" content="a tool to let your readers dive into details" />
<meta name="twitter:image" content="https://ncase.me/nutshell/pics/thumbnail.png" />
<meta property="og:type" content="website" />
<meta property="og:title" content="Nutshell: make expandable, embeddable explanations" />
<meta property="og:description" content="a tool to let your readers dive into details" />
<meta property="og:url" content="https://ncase.me/nutshell/" />
<meta property="og:image" content="https://ncase.me/nutshell/pics/thumbnail.png" />
</head>
<body>
<!-- BIG NUTSHELLS -->
<ul id="big_nuts">
<li id="pointys_target">
<a href="#WhatIsNutshell">:What is Nutshell?</a>
</li>
<li>
<a href="#HowDoIUse">:How do I use Nutshell?</a>
</li>
<li id="test">
<a href="#TipsOnWriting">:Tips on writing Nutshells</a>
</li>
<li>
<a href="#WhatInspiredThis">:What inspired this?</a>
</li>
<li>
<a href="#WhoMadeThis">:Who made this?</a>
</li>
</ul>
<!-- Pointy McPointFace -->
<div id="PointyMcPointFace"></div>
<!-- Preloading the splash animation -->
<iframe src="indexpage/splash.html" width="1" height="1" style="position:absolute; top:-100px; left:-100px;"></iframe>
<!-- Sharing -->
<div id="share">
<b>share:</b>
<br>
<a href="mailto:?subject=A%20tool%20for%20making%20%22expandable%22%20explanations&body=Thought%20of%20you%20when%20I%20saw%20this!%20Imagine%20if%20someone's%20reading%20your%20writing%2C%20and%20when%20they%20see%20a%20word%20or%20idea%20they%20don't%20know%2C%20they%20can%20click%20it%20to%20%22expand%22%20an%20explanation%20in-place.%20And%20if%20there's%20something%20in%20that%20explanation%20they%20don't%20understand%2C%20they%20can%20expand%20*that*%20too%2C%20and%20so%20on.%20Well%2C%20this%20tool%20lets%20you%20make%20stuff%20like%20that.%20I%20hope%20you%20find%20it%20helpful!%20https%3A%2F%2Fncase.me%2Fnutshell%2F" target="_blank">email</a>,
<a href="https://twitter.com/intent/tweet?text=Woah,%20this%20is%20trippy%20and/or%20very%20useful?&url=https%3A//ncase.me/nutshell/" target="_blank">tweet</a>
<br>
<a href="https://twitter.com/ncasenmare/status/1559953645151608833" target="_blank">retweet me</a>
<br>
<a href="promo">download pics+gifs</a>
</div>
<!-- The hidden nutshells -->
<hr>
<p>
<b>...and here's all the Nutshells made for this page:</b>
</p>
<!-- PASTE MACDOWN'S OUTPUT HERE, THANKS -->
<h1 id="toc_0">: What is Nutshell?</h1>
<iframe width="750" height="300" src="indexpage/splash.html" data-splash="yes"></iframe>
<p><strong>Nutshell</strong> is a tool to make "expandable, embeddable explanations", like this! They can even be <a href="#Recursion">:recursive</a>. (← click me 👆) This lets your readers learn what they need, just-in-time, always-in-context.</p>
<p>What's more, <strong>you can embed explanations from <em>other</em> webpages and authors, even stuff written <em>before</em> Nutshell was made!</strong> (Example: a snippet from <a href="https://blog.ncase.me/explorable-explanations/#ProceduralRhetoric">:my pretentious 2014 blog post</a>.) This works because Nutshell doesn't require writing in a new format – just good ol' headings, paragraphs, and links. This way, you don't have to write all your expandable explanations from scratch: you can just build upon others', and others can build upon yours.</p>
<p>But why not links? Well, unlike links, Nutshell lets you include <em>only</em> the snippet you need, not the whole page. And instead of a jungle of new tabs, your reader stays on one page, keeping their flow of reading. Even if you <a href="#Interruption">:interrupt a sentence</a>, Nutshell recaps the sentence afterwards, so your reader never loses context.</p>
<p><em>But wait, there's more!</em> It's not just text & pictures you can embed! You can also embed <a href="indexpage/malicious.html#InteractivePlay">:interactive playthings</a>, <a href="https://www.youtube.com/watch?v=i_RLYSaPvak">:YouTube videos</a>, and – hey, why not – <a href="https://en.wikipedia.org/wiki/Chicago_rat_hole">:Wikipedia articles</a>. (That includes <a href="https://fr.wikipedia.org/wiki/Baguette_(pain)">:other languages</a> and <a href="https://simple.wikipedia.org/wiki/Universe">:Simple Wikipedia</a>, too!)</p>
<p>So: whether you're writing a blog, a news article, a glossary, educational material, code documentation, etc... I hope Nutshell helps you help <em>your</em> readers.</p>
<p>Bite-sized, yet nutritious. Let's get crackin' with Nutshell!</p>
<h1 id="toc_1">: How do I use Nutshell?</h1>
<p>It's dead-parrot simple! Just copy-paste this <em>one line</em> onto your site: (<a href="#IncludingNutshell">:more details</a>)</p>
<iframe src='indexpage/include_nutshell.html?url=full' width='750' height='22' data-include='yes'></iframe>
<p>Then, to write a Nutshell snippet, just use headings & paragraphs. To embed a snippet, just make a link, but with a :colon in the front, <span data-fake-link>:like this</span>, so that Nutshell knows to make it expandable. (<a href="#CaveatOnLinking">:caveat</a>) <em>Click to play the below 1-minute tuorial video:</em></p>
<p><video width="615" controls>
<source src="indexpage/screenies/instructions.mp4" type="video/mp4">
oh no! your browser does not support the video tag. :(
</video></p>
<p>(even if you don't make links, the above one line of code makes all the sections of your blog post embeddable for <em>others</em>:)</p>
<p><img src="indexpage/screenies/embedthis.gif" data-border="yes" width="400"/></p>
<p>And that's all! To try Nutshell online, check out:</p>
<p>✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨<br>
👉 <a href="try"><strong>TRY NUTSHELL</strong>: the interactive demo!</a> 👈<br>
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨ </p>
<p>For more features & options, <a href="https://github.com/ncase/nutshell#advanced-features--options">check out the documentation!</a></p>
<h1 id="toc_2">: Tips on writing Nutshells</h1>
<p>If you'd like to explain something in a nutshell (ayyyy title drop), here's some advice:</p>
<ul>
<li>Show, <em>then</em> tell. Start with concrete examples & pictures, <em>then</em> lay down the abstract definitions.</li>
<li>Write your first draft, get a word count (you can use <a href="https://wordcounter.net/">wordcounter.net</a>), then cut 10% of your words.</li>
<li>This ain't Wikipedia. Use your own voice, not Neutralese.</li>
<li>I know recursion is fun, but <em>do</em> show restraint. <a href="#DontDoThis">:Don't</a> <a href="#DontDoThis">:stuff</a> <a href="#DontDoThis">:your</a> <a href="#DontDoThis">:explanations</a> <a href="#DontDoThis">:with</a> <a href="#DontDoThis">:Nutshells</a> <a href="#DontDoThis">:like</a> <a href="#DontDoThis2">:this</a>. Embed only what's essential.</li>
</ul>
<p>For more advice, see <a href="https://youtu.be/ojjzXyQCzso?t=512">:3Blue1Brown on making math explainers</a>, my <a href="https://www.youtube.com/watch?v=b-M2U3Jl1Cg#with_summary">:Stanford mini-talk</a>, or <a href="https://ncase.me/faq/#writing_accessible_explanations">:my FAQ</a>.</p>
<h1 id="toc_3">: What inspired this?</h1>
<p>Once upon a time, back when folks believed connecting the world's people would birth a new era of empathy and enlightenment (ha ha h<em>a hA HA HAAAAA--</em>)</p>
<p>...in that time, the inventor Ted Nelson proposed something called <strong>StretchText</strong>. The idea was this: you're reading an article at a high-level, but can "stretch" sentences into more detail. Then you can stretch <em>that</em> detail into more detail, and so on, while everything stays in one continuous context.</p>
<p>(See <a href="#StretchTextOriginal">:its original 1967 design document</a>, and Nelson <a href="https://youtu.be/Bqx6li5dbEY?t=150">:showing it off in a Werner Herzog documentary</a>)</p>
<p>Since then, the idea's been re-discovered a few times. In 2008, a viral website named <a href="https://www.telescopictext.org/text/KPx0nlXlKTciC">Telescopic Text</a> let you stretch "I made tea" into a short story. In 2018, Wikipedia added a "hover to preview article" feature. (<a href="#MoreStretchTextLikes">:more StretchText-likes</a>)</p>
<p>And now, in 2022, I give you Nutshell! My main value-add, compared to previous StretchText-likes, is that you can embed snippets from <em>other websites & authors, even stuff written long ago</em>. That way, we can build upon each others' explanations.</p>
<p>Hey, maybe <em>that'll</em> birth the new era of empathy and enlightenment!</p>
<p><code>NARRATOR: it won't.</code></p>
<h1 id="toc_4">: Who made this?</h1>
<p><a href="#NickyCase">:Nicky Case</a> is to blame for this thing. This thing is <a href="#OpenSource">:open source</a>, available <a href="https://github.com/ncase/nutshell">on Github</a>.</p>
<p><strong>Special Thanks to</strong>: Andy Matuschak, DominoPivot, Mike Cook, NachoBIT for gifting early feedback; <a href="https://github.com/spaciecat">Kaira Imer</a> for writing code on an previous version; <a href="https://twitter.com/ProQuesAsker/status/1440125223685165061">Amber Thomas</a> for inspiring the "dots opening & closing" animation.</p>
<p>Nicky <strike>panhandles on the internet</strike> was supported by these kind folks:</p>
<iframe src='https://ncase.me/thanks/aug2022.html?credits=1&v=2' width='750px' height='400px'></iframe>
<p>If you'd like to help Nicky keep making free educational stuff & talking about themselves in the third person, dispose of your disposable cash <strong><a href="https://www.patreon.com/ncase">on her Patreon!</a></strong></p>
<p>But seriously, thank you to everyone above. I appreciate y'all.</p>
<p>🥜,<br>
~ Nicky Case</p>
<p><strong>Update Oct 11, 2024:</strong> Also thank you to <strong><a href="https://github.com/Dev-Mehta">Dev Mehta</a></strong> for adding the ability to use Nutshell on <em>specific</em> Wikipedia sub-sections, and with recursive expandable links! Like so — <a href="https://en.wikipedia.org/wiki/Binary_number#Addition">: Binary Addition</a></p>
<h2 id="toc_5">: Recursion</h2>
<p><img src="indexpage/sprites/recursion.gif" data-float="left" width="200"/></p>
<p><strong>Recursion</strong> is when something contains a copy of itself. It's often used in math and programming, to get infinite potential out of finite stuff.</p>
<p>See also <a href="#recursion">:recursion</a>.</p>
<h2 id="toc_6">: Interruption</h2>
<p>all work and no play makes jack a dull boy all work and no play makes jack a dull boy all work and no play makes jack a dull boy all work and no play makes jack a dull boy all work and no play makes jack a dull boy</p>
<h2 id="toc_7">: Wikipedia's Hover To Preview</h2>
<p>This thing:</p>
<p><img src="indexpage/screenies/wiki.gif" alt="" title="a GIF showing Wiki's hover-to-preview feature; when a cursor hovers over a link, a preview of the article shows up in a bubble"></p>
<p>It only goes one level deep & only previews a few paragraphs, but it <em>is</em> helpful, and an inspiration for Nutshell.</p>
<p>Wikipedia is cool, ok? Give Jimmy your money.</p>
<h2 id="toc_8">: Including Nutshell</h2>
<p>To install Nutshell, you need to be able to edit the <a href="#HTML">:HTML</a> of your blog/site. Here's instructions on how to do so <a href="https://wordpress.com/support/adding-code-to-headers/">for WordPress</a>, <a href="https://help.tumblr.com/hc/en-us/articles/230778847-Custom-HTML">for Tumblr</a>, and <a href="https://ghost.org/tutorials/use-code-injection-in-ghost/#add-js-to-the-site-footer">for Ghost</a>. I personally use <a href="https://pages.github.com/">GitHub Pages</a>.</p>
<p>Just paste this one line of code anywhere, preferably the header:</p>
<iframe src='indexpage/include_nutshell.html?url=full' width='750' height='22' data-include='yes'></iframe>
<p>Or, smaller "minified" file:</p>
<iframe src='indexpage/include_nutshell.html?url=min' width='750' height='22' data-include='yes'></iframe>
<p>(You can also download & re-host the files yourself {<a href="https://cdn.jsdelivr.net/gh/ncase/nutshell/nutshell.js">full</a>, <a href="https://cdn.jsdelivr.net/gh/ncase/nutshell/nutshell.min.js">minified</a>}. Also, Nutshell doesn't require a package manager; I copy-pasted all dependencies into it. Like a <em>savage</em>.)</p>
<p>Alas, some platforms like Medium and Substack don't let you add <em>any</em> code, not even <em>one line.</em> You can't use Nutshell on those platforms. 😿</p>
<h2 id="toc_9">: HTML/CSS/JS</h2>
<p>Webpages are made of code. Specifically, 3 kinds of code: HTML, CSS, and JavaScript.</p>
<p><strong>HTML</strong> is the page's raw content. (HTML = HyperText Markup Language)</p>
<p><strong>CSS</strong> tells the page how to be stylish. (CSS = Cascading Style Sheets)</p>
<p><strong>JavaScript</strong> tells the page how to be interactive. (JavaScript has nothing to do with the programming language Java. It was... some marketing thing? Ugh, programming sucks.)</p>
<h2 id="toc_10">: Caveat on Linking</h2>
<p>Alas, an annoying catch: the other webpage needs to <em>also</em> have Nutshell installed, or <a href="#CORS">:CORS</a> enabled. If you own the other page, that's not a problem! But if not, you'll have to mirror/copy the other page. Sorry!</p>
<h2 id="toc_11">: CORS</h2>
<p><strong>Cross-Origin Resource Sharing (CORS)</strong> are rules that exist because web security programmers are paranoid, and rightfully so.</p>
<p>Let's say you're visiting Facebook.com. Your web browser (Firefox, Chrome, Safari, Microsoft Edge, etc) pings Facebook, and Facebook gives you back your personal info. So far so good.</p>
<p>But now let's say you visit TotallyNotCyberCriminals.com. <em>If it weren't for CORS, this could happen:</em> the sneaky site makes your browser ping Facebook, Facebook sends back your info, and <em>bam</em>, the sneaky site now has your info. (Well, a different sneaky site.)</p>
<p>Browsers <em>could</em> say, "A site can only get info from itself: Facebook can only get info from Facebook, etc". But that'd make it impossible to do cool web things, like Nutshell.</p>
<p>So the security programmers chose a compromise: Site X can get info from Site Y <em>only if Site Y says Site X (or *all* sites) can have it.</em> These are rules for sharing resources across different sites, different origins. Hence: "Cross-Origin Resource Sharing".</p>
<p>P.S: <a href="#CORSForWebDevs">:a message for you web developers</a></p>
<h2 id="toc_12">: CORS For Web Devs</h2>
<p>If your webpage has no private info, I highly recommend setting your CORS rules to "<em>everyone</em> can get this page's info". That way, cool tools like Nutshell can easily embed your stuff!</p>
<p>Check out <a href="https://enable-cors.org/">Enable-CORS.org</a> for how to do this. Personally, I host all my sites on <a href="https://pages.github.com/">Github Pages</a> – <em>I promise this message is not sponsored</em> – which enables permissive CORS by default.</p>
<h2 id="toc_13">: Don't Do This</h2>
<p>don't do this.</p>
<h2 id="toc_14">: Don't Do This 2</h2>
<p>you just <em>had</em> to open all of these, didn't you?</p>
<h2 id="toc_15">: Stretch Text Original Document</h2>
<p><img src="indexpage/screenies/StretchText.png" alt=""></p>
<h2 id="toc_16">: More StretchText-Likes</h2>
<p>From top-to-bottom: <a href="https://en.wikipedia.org/wiki/Wikiwand">Wikiwand</a>, <a href="https://en.wikipedia.org/wiki/LessWrong">LessWrong</a>, <a href="https://www.gwern.net/">Gwern.net</a>⤵ ("retweets are not endorsements", yadda yadda...)</p>
<p><img src="indexpage/screenies/stretchtextlikes.png" width="500"/></p>
<p>There's probably many more StretchText-likes, but I haven't heard of 'em.</p>
<h2 id="toc_17">: Nicky Case</h2>
<p><img src="indexpage/sprites/nicky.png" data-float="left" width="200"/></p>
<p>Nicky Case is an internet person who explains stuff with games, "games", and pictures with words. See what she hath wrought at <a href="https://ncase.me">ncase.me</a>.</p>
<h2 id="toc_18">: Open Source</h2>
<p><strong>Open source</strong> code is (<em>usually but not always*</em>) code that's free to use, remix & re-distribute – even for profit, with no or few** requirements.</p>
<p>* "Free" is an annoyingly confusing word. <em>Very roughly speaking,</em> think "free as in freedom of the press", not necessarily "free as in Wi-Fi at Starbucks."</p>
<p>** One common requirement is "give credit". Fair enough. Some open source licenses go further: they require that your remix <em>also</em> be published under the same license. These are called <strong>copyleft</strong> licenses. Licenses without that requirement are called <strong>permissive</strong> licenses.</p>
</body>
</html>