3b1b/3blue1brown.com

3Blue1Brown Website

This is a Next.js project bootstrapped with create-next-app.

Build the site locally

1. Install Node
2. Install Yarn
3. Install Git LFS
4. Install an MDX syntax highlighting plugin for your code editor
5. If installing Git LFS for the first time on your user account, run git lfs install
6. Run yarn dev
7. Open http://localhost:3000 to see the site

Background Knowledge

Basic

What you need to know if you're just authoring lessons or otherwise editing .mdx files:

• Git
• GitHub
• Markdown
• MDX
• YAML

Advanced

What you also need to know if you're editing the website more in depth:

• HTML
• CSS
• Sass
• JavaScript
• React
• JSX
• Next.js
• create-next-app
• Yarn
• Node
• GitHub Actions
• webpack

Guidelines

Guidelines to ensure consistency and quality of contributions are listed in .github/pull_request_template.md. Some items may refer back to this readme for longer lists or documentation.

Components

Components (or "widgets") are building blocks for visual and interactive elements that go beyond basic Markdown. You can use components in your .mdx files and pass them options/parameters called "props".

The basic syntax is:

<SomeComponent someString="some string" someNumber={42} someFlag={true} />

Or for some components that may need longer-form inputs:

<SomeComponent>Lorem ipsum dolor</SomeComponent>

The inner contents are referred to as the children prop below.

This section only covers the components and props meant to be used in lessons. For documentation of other components and props, look in the components folder.

• 📚 = prop accepts markdown and math
• 🚨 = prop is required for component to render

Accordion

An expandable/collapsible section.

• title 🚨 - Text to show in clickable button that expands/collapses more content beneath.
• children 🚨📚 - Content to show under title button when expanded.

Center

Centers a group of arbitrary elements. You shouldn't need to use this in lessons much, if ever. Most components align themselves as stylistically appropriate.

• children 🚨 - Arbitrary content.

Clickable

A button is an element that does something on the current page. A link is an element that goes somewhere. This component is a big clickable that combines the two for stylistic consistency, hence the generic name "clickable".

Normal in-text links can still be made with regular Markdown syntax. This component is used outside of lessons, but in lessons you should only use this component for important links you want to emphasize.

• link 🚨 - Location to go to when link is clicked.
• icon - Font Awesome class of icon to show next to text.
• text - Text to show.
• design - Style of the clickable. rounded for rounded. Default "" for square.

Also required: icon or text

Figure

A component to show image and/or video and caption, with controls to switch between them.

• id - A page-unique identifier like some-figure to attach to the figure so you can link to it like [Some Figure](#some-figure).
• image 🚨 - Path to image file.
• video 🚨 - Path to video file.
• show - Whether to show image or video by default. One of "image" or "video".
• caption 📚 - Caption for both image and video.
• imageCaption 📚 - Caption just for image.
• videoCaption 📚 - Caption just for video.
• width - Manually set width like 300px. Displayed width will never go beyond screen.
• height - Manually set height like 300px.
• loop - Whether to loop video, true or false.

For image and video, if you provide a relative url, links to that path in the Linode bucket. Omit width and height whenever possible to let the figure auto-size based on the aspect ratio of the image/video.

Interactive

Dynamically imports another react component and displays it in a frame.

• filename 🚨 - Name of a .js file (without the extension) in the same folder as the lesson.
• children - A function that takes the component loaded from filename and returns what to render (allows passing props to the loaded component).
• aspectRatio - A number representing the width / height of the box in which the interactive lives. (Default: 16 / 9)
• allowFullscreen - A boolean indicating whether to show a full screen button in the top right (defaults to false)

Example of children: <Interactive>{(MyComponent) => <MyComponent someProp="some value" />}</Interactive>.

Lesson Link

An in-text link to another lesson that shows a preview of the lesson in a tooltip on hover/focus.

• id 🚨 - Identifier slug for lesson, like quick-eigen.
• children - Link text.

Pi Creature

A pi creature with a chosen emotion and optional speech/thought bubble text.

• emotion - Filename of emotion in /pi-creatures folder. Default hooray.
• text 📚 - Text to show in bubble. Omit to not show any bubble.
• thought - Whether bubble is thought (true) or speech (false). Default false.
• placement - How to place the pi. side puts the pi to the right of the main page column (with its bottom aligned with the bottom of the previous element, which can be a paragraph, figure, etc.), and hides the pi completely when the screen isn't wide enough. inline puts inside the main page column as if it were its own paragraph. auto puts the pi to the side when the screen is wide enough, and inline when it isn't. Default auto.
• flip - If true, puts the pi to the left instead of the right.

Question

Interactive multiple-choice question with explanation.

• question 🚨📚 - Text of the question
• choice1 through choice6 🚨📚 - Possible choices.
• answer - Which choice number is the correct one, e.g. answer={3}.
• explanation 📚 - Explanation of answer once reader gets it correct.

Section

Sections are the alternating white/off-white backgrounds that span the entire width of the page. Use these sparingly to divide your lesson into big groups.

• children 📚 - Arbitrary content.

Example:

... previous section of content

</Section><Section>

... next section of content

Spoiler

"Redacted" text that reveals itself on hover/focus, similar to spoilers on Reddit and other forums.

• children 📚 - Arbitrary content.

Twitter

Component to embed a tweet (and possibly other Twitter things in the future?).

tweet 🚨 - Id of tweet.

3blue1brown.com's Issues

Automatically size figure to always look good and fullscreen on click

Right now we're leaving it up to the author to size each image/video manually, eg. width: 60% or height: 300px. Maybe, to enforce consistency, we can figure out some algorithm that automatically sizes it such that it always looks good and consistent. We could always keep the manual sizing there for special cases, I suppose.

@3b1b thoughts?

Also, for the sake of detailed figures, we could have the image/video pop out and become full screen on click. Though I don't recommend making a figure so detailed that this is absolutely necessary, because if it has that much fine detail, it won't be legible on mobile even when full screen. Though, still a nice option to have. Browsers already have built-in controls for fullscreening videos so we'd only need to implement it for images.

"Aside" component

Need some kind of footnote or aside component. There are several ways to do this.

One is by having a tooltip, but this is difficult and a bit hacky to do. Another is by having an accordion the reader can expand/collapse, but this, design wise, only makes sense for non-mid-sentence asides (it'd have to go after a full paragraph).

A perhaps temporary solution we came up with is: have a superscript icon or number that when clicked on expands a hidden paragraph below the current paragraph with rich content.

Need to experiment with this to figure out what the best doable solution is.

Question component explanation

As per #60, and also #58, the question component should have an explanation, and this explanation should have some styling that makes it stand out clearly from the article. I'm guessing lower width and clearly distinct background color?

The explanation is likely to be larger than the question, and if we have to choose which one gets full markdown, it should be the explanation.

Separate question: Should "show explanation" be a separate operation from "check answer"?

Linode Object Storage Setup

This guide has the steps for setting up Linode object storage.

If you would like me to setup the bucket I'll need an login with a payment method. Otherwise, I think the general steps are:

1. Create a bucket and upload a test file.
2. Allow Public Read Access for objects via Cloud Manager. See this doc for full details.
3. Install the Linode CLI for programmatic upload/download/delete abilities.
4. Generate access tokens for team members to allow programmatic access.

Table of contents plugin?

Maybe incorporate a table of contents plugin -- for the page, not for the site-wide lessons and topics -- somehow into the side? Perhaps useful for longer lessons where jumping between sections would require a lot of scrolling. Along with this, a floating jump-to-top button?

Distinguish series from non-serial groups

Some groups of topics (linear algebra, calculus, differential equations, neural networks) are meant to be a contiguous series, whereas all the others are more just collections of topics with similar topics/genres. It might make sense for the design under the "by topics" tab to reflect this.

Then, for those groups which are meant to be series, it might make sense to display the chapter numbers with a separate design around their titles.

Abandon default GitHub Pages

Right now, the site deploys to GitHub Pages automatically, with no extra configuration. Downside is GitHub Pages significantly restricts what Jekyll functionalities you can use, for security reasons.

We will likely want some Jekyll plugins that gh pages doesn't support, like last-modified-at (automatically assigns a last-modified date to each page) and paginate-v2 (allows a statically generated page for each tag).

All this will cost us is: 1) the repo will have a separate gh-pages branch in addition to main which holds the built version of the site and 2) we'll need a small yaml file to config GitHub actions to build the site and push the result to the gh-pages branch every time there's a push to main.

Normally GitHub does these things by default, behind the scenes, hidden. Originally, I wanted to keep things as clean as possible, but these things are easy to do and add more functionality. A side benefit is we'll also get better build logging.

Discussion of image scaling and page width

If we change the content width on the site to be a number with more factors than 1000, such as 960 or 1080, then it will make designing grid layouts and custom illustrations a little easier and IMO more pleasing. Namely, 1000 is missing the factor of 3.

Note: This is pretty nit-picky since 1000px is perfectly fine.

To illustrate why this might be nice, consider that 960 can be evenly divided by common numbers and the results also have a lot of factors too.

960/2 = 480
960/3 = 320
960/4 = 240
960/5 = 192
960/6 = 160

For completeness, shown below are the prime factorizations of the three numbers 960, 1000 and 1080.

960=2*2*2*2*2*2*3*5

1000=2*2*2*5*5*5

1080=2*2*2*3*3*3*5

Fourier pi animation

In JS + SVG for clean res

freq's and coeff's

0 (-0.5171496323199052-0.29875690272317473j) 1 (0.45089733300671836-2.360213974892882j) -1 (-0.006324839942986183+0.26730083171783187j) 2 (-0.5080236411498863+0.914199877044051j) -2 (-0.08601273401302247+0.3224446438679854j) 3 (0.4664985917359486+0.31791675990228646j) -3 (0.36649151247650524+1.0889926473106584j) 4 (-0.4398007640653272+0.17254529443351238j) -4 (-0.3023485402514777-0.20954750776997136j) 5 (0.3224671927023517+0.15813940976855698j) -5 (0.04544572298881235+0.17188647323600023j) 6 (-0.10330416201374433+0.13582978042723043j) -6 (0.03482428652883792+0.5022019486149555j) 7 (0.12057837494530113+0.17341654053123598j) -7 (-0.052421257816614275-0.024246254327112766j) 8 (0.1302984347030619-0.16888463050056116j) -8 (-0.21600302717824615+0.07378620859151415j) 9 (0.10272606320428415+0.16387101359578118j) -9 (0.053941215591348145+0.1774916591207604j) 10 (-0.01363369811261597+0.003004792149161608j) -10 (0.0006270524712188604+0.08384870871002072j) 11 (0.044037323318118854+0.01205397773653043j) -11 (-0.19693604537462447-0.020196305060212003j) 12 (0.11041964942410135-0.018789140065217057j) -12 (0.04077787580892597+0.08799210699451956j) 13 (-0.06605212570676816+0.04299638992605215j) -13 (-0.029214705849833416+0.05987282304884375j) 14 (0.06627735931006787-0.030060880963359776j) -14 (-0.08872087759103961-0.024549854685669413j) 15 (0.074230755924456-0.02102169310352062j) -15 (-0.0696120310643163+0.08527079456313154j) 16 (0.008996129172763342+0.03735217590678535j) -16 (-0.011489915745653582+0.011737309215594764j) 17 (0.00597776886043933-0.016246278898773676j) -17 (-0.026686946200915215+0.03550836339366196j) 18 (0.03705040278545465+0.011183856850663313j) -18 (-0.0723160054313746+0.011015716809754446j) 19 (0.03094322402752083+0.03345418898006537j) -19 (0.013254377610190063+0.054356188748196796j) 20 (-0.03582539557099598+0.009932305927399833j) -20 (-0.018616560785129816-0.013026886192823179j) 21 (0.01610052004297019-0.009372099036816503j) -21 (-0.002539573139422953-0.013557528938804927j) 22 (-0.0065309375243681024+0.001834098494182598j) -22 (-0.01583720475098143+0.037860901556324544j) 23 (-0.027550288510711025+0.02083072783400731j) -23 (0.02626797527831164-0.03307698558803917j) 24 (-0.005465416610776751-0.04086678754934176j) -24 (-0.013579353552134904-0.01746243829101132j) 25 (-0.0127092397131536+0.011129860284610672j) -25 (0.0032716511159311084+0.0014461719555735472j) 26 (-0.018562891151830872+0.009204203607914753j) -26 (0.02087533472814655+0.008067886497069236j) 27 (-0.019883882013270193-0.006381366160272836j) -27 (-0.013770711842473794-0.028424442005116658j) 28 (0.003952453958146282-0.004661820219499845j) -28 (0.010209486696345676+0.004235887172466329j) 29 (-0.028082199956767508+0.01118982265924495j) -29 (0.009794003866430786+0.008054165572408283j) 30 (-0.0037650449805868135+0.01421178681986817j) -30 (0.004590435826057264-0.007381164334475983j) 31 (-0.0033090854049413567-0.003982100770127758j) -31 (-0.006685149229326567-0.00042807586218278576j) 32 (-0.005489356892219184+0.015516495602630085j) -32 (0.013940844799591663+0.0038306808455420257j) 33 (-0.010436723370980852+0.009601662140315778j) -33 (0.008639374328139627+0.004468813982107571j) 34 (-0.0006484090619401173+0.008084971936155287j) -34 (-0.005326703311769967-0.003139181441395171j) 35 (0.0021459552959285392+0.002798694676079833j) -35 (0.009732367098905523+0.0039102294765781314j) 36 (-0.01315286668265091+0.01022861251417351j) -36 (0.014172811482140998+0.0002509748561738519j) 37 (-0.005915574575831655+0.003772763685509168j) -37 (0.00428170962024175+0.0005771303496796292j) 38 (-0.0023852167409938205+0.004951282103241181j) -38 (0.005550256900849664+0.0017511548138345518j) 39 (-0.00667192815549195+0.0009980781254250403j) -39 (0.008816636898837056-0.005420599162952502j) 40 (-0.005721510037290841-0.00021475335705505358j) -40 (0.0028301054664458167-0.00016799138783949843j) 41 (-0.0017069712205113753+0.001636390283677406j) -41 (0.0032877701325300167+0.0025329050437014546j) 42 (-0.0018129460806745586+0.00101383756599369j) -42 (-0.0009839687547631884-0.0014210550948724205j) 43 (0.004954812822835514-0.002102739074771654j) -43 (-0.0029074947521359803+0.0028771971056740227j) 44 (0.0011922077698935227+0.003984374261066617j) -44 (0.0016369778948329356+0.0052684726307526235j) 45 (0.00274762535793503+0.002943721485229824j) -45 (-0.0014515175134054289+0.00456901659308981j) 46 (0.0067029125357252715+0.0027739230161983016j) -46 (-0.008466920058004795+0.00867655607638477j) 47 (0.0058028310567250635+0.005783613976422458j) -47 (0.002191665836150312+0.0036342453420068637j) 48 (-0.002068991791244099+0.0005032091522110889j) -48 (0.0010436865053037806+0.006158345456233693j) 49 (0.00353406784853249+0.004174038079318263j) -49 (-0.005455136009568039+0.005982451927631608j) 50 (0.0073616676849982444+0.0031057373121448338j) -50 (-0.0029272876279946842+0.007737903236264538j)

Interactive demos gallery?

Perhaps have a gallery of interactive/react apps that looks sorta like this:

Perhaps it would live as another tab next to "featured" "by topic" and "by date".

Something to workshop once we have more interactive apps.

Spruce up 404 page

Add sad pi with heart broken. Maybe something else fun.

Include site-wide search when we have that ready per #24

Use 16:9 yt thumbnails

maxresdefault.jpg instead of hqdefault.jpg

Numbered and tooltipped figures, equations, citations, etc

Some kind of automatic numbering and id'ing of figures, equations, and more, similar to Manubot.

Cursory thought on implementation: have the appropriate components be able to accept an id field, like {% include figure.html id="fft-derivation" image="fft.png" %}, then you can link to it elsewhere in the doc simply like [Link Text](#fft-derivation).

Then we can have a javascript plugin or ruby plugin replace "Link Text" with automatic numbering. May need prefixes somewhere like fig: or eq: to distinguish between the types.

Related to #26 and #19 , think holistically.

Figure out where to put recommendations?

Such a long word, really takes up a lot of space in the header. Perhaps put it on the "Extras" page? Or have it as a separate page, but don't link to it in the header, but instead link to it at the top of Extras or About with a big button?

Question component tweaks

Don't show correct answer when selecting wrong one. Show reset button after submitting.

Topic descriptions

Add a short text description to each of the lesson topics (Calculus, Linear Algebra, etc.), which will become visible upon expanding a given topic.

Hugo Errors

I'm opening this issue about error reporting in Hugo with the goal to prevent silent failures and generate more meaningful errors for authors and developers while working with Hugo. This can be pretty subtle when managing the dot context, but when setup correctly it's no big deal and will make our lives better.

TLDR: Give more useful errors to content authors and prevent silent failures when content changes.

General Example

As a general example, this example figure shortcode matches a page resource (image) based on a path supplied by the user. For example, the user might write the shortcode shown below in their markdown file.

{{ figure image="example.png" }}`

The shortcode template looks like this:

{{ with .Page.Resources.GetMatch $path }}
  {{/* TODO: render here */}}
{{ else }}
  {{ errorf (printf "%s: Unable to find resource given the path:\"%s\"" .Position $path) }}
{{ end }}

Then, when the author types a bad file path they'll get a shorter, better error. Specifically, the line number where the failure occurred and the input that caused the error.

ERROR 2021/05/25 10:27:29 "~/Sites/3Blue1Brown.com/content/lessons/2021-05-22/index.md:12:1": Unable to find resource given the path:"bad-file-path.png"

There are a number of other considerations for the actual figure shortcode. For example, what happens if the "image" or "video" attribute is misspelled or not present.

Silent Failures

In addition to making the error messages more helpful, managing errors and warnings ourselves gives us the added benefit of preventing silent failures when editing the site. For example, the lesson gallery shortcode is a currently a good example, because if you change data in the data/featured.yaml file or, just as likely, change the path of a lesson in the content directory, the current behavior is silent failure - the bad id fails silently and no lesson card is rendered.

Currently on line 34-36 in layouts/partials/lesson-gallery.html the lesson card partial is used. If a bad id is passed to the partial, this renders nothing when it probably should report an error.

{{ range $featured := site.Data.featured }}
  {{ partial "lesson-card" (dict "id" .) }}
{{ end }}

An error can be thrown in the partial, and probably should throw one if the partial expects and string id and calls GetPage. However, I would recommend that we provide a more better error message here and instead pass the lesson page context and additional values to the partial.

{{ range site.Data.featured }}
  {{ with site.GetPage . }}
    {{ partial "lesson-card" (dict "context" .) }}
  {{ else }}
    {{ errorf (printf "data/featured.yaml: Unable to find the lesson associated with the id:%s" . )}}
  {{ end }}
{{ end }}

The same applies for the data/topics.yaml file. For example, before the last commit, adding this check to lines 43-45 in layouts/partials/lesson-gallery.html reports the three errors shown below while testing.

ERROR 2021/05/25 13:57:42 data/topics.yaml: Unable to find the lesson associated with the id: "quick-eigen"
ERROR 2021/05/25 13:57:42 data/topics.yaml: Unable to find the lesson associated with the id: "qa1"
ERROR 2021/05/25 13:57:42 data/topics.yaml: Unable to find the lesson associated with the id: "qa2"

Summary

In general, I agree with Vince that first priority is errors that content authors run into, usually associated with shortcodes, data files and adding/editing lessons in the content directory. If we run into an obscure error in the future, we can always review it and see if we can provide a better one.

Switch to Hugo?

https://gohugo.io/hosting-and-deployment/

@kurtbruns , would be good if you could list some bullet points of things you like about it. I've personally gotten frustrated with Jekyll more than once, I just chose it because I thought it would be easier for Grant to maintain in the future.

Hugo does seem to have a "jekyll import" function that hopefully works nicely.

Option for figure captions to change based on view mode

Unless I am mistaken, the figure caption remains the same for both the Still and Animation tabs, but it makes sense to have a separate caption for certain cases where the still needs a bit more explanation.

Workflow Development

Goals

Our workflow should be robust, easy to us and leverage the benefits of git and Github.

I.e. an author in a local environment should be able to view and make changes without worrying about the live site or data constraints. Then, when it comes time to push changes to the live site, they are able to publish changes quickly and confidently through a pull request. They should also have the ability to roll back to a previous commit.

Current Workflow

Currently we use Github Actions to publish the live site to Github Pages. We also use Vercel to preview the site via a pull request. This workflow is simple, easy to use and well integrated into Github.

Due to high number of expected users, we plan to use store large static assets such as images and animations (.mp4, .mov, .png) on a Cloud Object Storage service. The proposed workflows below are suggestions for how we can extend our current workflow to use buckets.

A Simple Workflow

This workflow uses two buckets called development and production.

While editing content, authors interact with the development bucket to add/edit/delete files. This would be done through the Linode CLI or Cyberduck. I tested this workflow using Cyberduck and it is easy to setup and use. We would mirror the _posts directory structure in the bucket.

To push changes to the live site, a pull request is created that generates a preview of the site with assets that use the development bucket. Then, either through manual action, a script or github action, the production bucket is synced with the development bucket and the pull request is merged.

Considerations:

• Assets live outside of git.
• Checking out a specific version of the site is difficult.

A solution for the two considerations above is to take a snapshot of the production bucket before a pull request is merged. This snapshot would be saved with the commit hash and would allow us to recover/roll the live site back to a previous commit.

A Better Workflow*

This workflow has authors edit and commit large assets into VCS. Github actions would be used orchestrate local, staging and production environments using feature branches, a development branch and a main branch.

The author would edit local markdown files and assets that live next to each other.

example-post/
├── YYYY-MM-DD.md
├── animation-1.mp4
├── animation-2.mp4
├── figure-1.png
├── figure-2.png
├── ...

When the author is satisfied with their changes they push to the development branch. This creates a development site available at a public URL. If the author wants to roll back changes, they can revert to a specific commit and push to the development branch again.

Once changes have been staged in the development branch, a pull request for the main branch is created. Once accepted, this applies the changes in the development branch to the live site. This is the same workflow as pushing changes to the development branch.

Technical Details

This workflow uses git large file storage in combination with Linode Object Storage (see #38) to manage the static files in two buckets: a development bucket and a production bucket. When pushing changes to the development or main branch a git action is run that syncs the bucket with the current commit.

See s3 sync action as an example.

The local site would serve local assets while authoring content using something like Jekyll Environments. These assets would be published in the build directory for the local, but not the development or production environments. I know this is possible in Hugo #34 , but may not be with Jekyll.

Lesson "featured", "by date", and "by topic" tabs

Splitting this out from #4 into it's own separate issue. Maybe have a button to toggle between showing the topic cards, and just a chronological listing of lesson cards. Wouldn't actually be too hard to do.

Could i contribute even though I do not get the internship?

Dear Grant, even though I do not have the internship opportunity, could I still make some contributions on this project? Thank you!

Citations

Some method (probably another component) to put citations into lessons. Cursory thought: we have a site-wide citations.yaml in /_data that can be populated like:

- id: doi:10.10101
  title: How to add numbers
  author: Isaac Newton
  publisher: Me
  year: 2030

...

and displayed like {% include components/citation.html id="doi:10.10101" %}, and we make the citation component look how we want and have the fields we want.

This component will probably need to integrate with the "aside" component in #19 . Think holistically here.

404 Page Search Link is Broken

Currently the 404 page has a link to the search page, but the link is https://3blue1brown.netlify.app/search%20%7c%20relURL%20, which serves another 404 page because of the extra characters at the end of the search URL.

Distinguish series from non-serial groups (chapter numbers)

Abstract chapter number to front matter field eg

chapter: 1

Sketches:

Home page gallery tweaks

From a previous email:

What are your thoughts on populating the home page with a gallery of thumbnails, something with minimal text and just imagery? One could toggle between seeing them organized by category or just listed by date created, and upon clicking a thumbnail it expands to show the title and a short description.

We could add a dropdown/toggle for this. But perhaps let's consider this an enhancement, since 1) we already have the latest video above the topics and that's probably what most people are looking for in terms of chronology? 2) the topics are probably a better jumping off point than date? 3) YouTube already has a functionality to list things by upload date.

Also, perhaps each card should have two links on hover: a link to the video on youtube and a link to the written blog post?

Also perhaps simplify the Follow and Support sections? Less text, maybe collapse them into a single, two-column section below the topics section? Ultra-minimal.

Chips for text-version and other things

We have chips for chapter coming in the next PR. It'd be good to have chips for other important things like, "this lesson has a text version ready", and less importantly, "this lesson has interactive elements".

Extas page and site header organization

I'm Just leaving a note here for what content would be referenced on the extras page. Completely open to suggestions on the best design surrounding it.

Stuff to put on extras page:

• Interactive videos on quaternions
• Interactive(ish) versions of lockdown math lectures
• MIT 18.S191
• Multivariable calculus videos and article on Khan Academy
• TEDx Talk
• Ben, Ben and Blue
• Silly math poetry
• Contributions to Quanta
• I've tried to track contributions to other channels here.

Handling translations

This is vague and will encompass many things, but it's worth recording some thoughts on the best way to include translated content into the site. Honestly, this is more about managing the 3blue1brown YT channel(s) than the website development, but there is some crossover.

• There are numerous dubbed versions of the videos (see here), and it would be elegant to allow users viewing a post with an embedded video at the top to select a language when the dubbing is available.
  • This might mean adding more metadata to an article indicating the URLs of translations.
  • Since the content on Bilibili is pretty comprehensive, there might be value to embedding those.
• I need to find a good tool to manage crowd-sourcing subtitle contributions to YouTube videos, but once that's in place, we should have a place on the site that clearly points people to it and invites contribution. At the very least this could be the FAQ, but it may make sense to place it elsewhere.
• If people want to submit translations of the articles, it may be worth having a means of allowing that (or finding a tool to help crowdsource reviews of it), then add the ability to toggle between languages for the written version of each post.

Width of internal link preview

The tooltip preview of internal links sort of runs awkwardly against the edge when the description is long. I think we should decrease the maximum width it can have, and also give it some buffer against the edge of the screen.

Table of contents tweaks

Some thoughts on the table of contents. These are mostly (entirely?) shamelessly lifted from the design of the sidebar on Wikiwand.

• As soon as one scrolls down to the article, the table of contents should appear on the right by default.
  • But only if the screen is wide enough, of course.
  • As a side note, I think it might look nice to have the width of the article content a bit thinner, maybe around 900px instead of 1080px
• Instead of saying "Lesson sections" on the top it should either be nothing, or the title of the article.
• The name of the section where the reader current is should be highlighted (or somehow indicated) in the sidebar, so as to give an at-a-glance sense of how far in the lesson they sit.
• (Nice to have, not critical) in clicking to a new section, rather than jumping to it there should be a quick animated scroll to the appropriate position.

Top of the lesson page layout

I'm just recording a few small notes here so I don't forget.

• Arguably the video embed should go above the title, dates, byline, etc. in the top of the lesson.
  • That way, when a person clicks on a lesson, what dominates the screen is an actual lesson rather than descriptors.
  • Having the title below the video also matches how its shows up on YouTube. Not that they need to match, but it's a positive signal for the video-at-the-very-top design.
  • The title, dates, byline, etc. then serve as a kind of separator between video content and written content.
• Would it be crazy to have the video fill the full width of the page, analogous to the YouTube player's "theater mode"?
• Instead of displaying the group of the video below the byline, save the screen real estate and just don't display it at all, but maybe show it if someone clicks to open the lesson list (probably shown at the top of the list).
• Given that realistically it will take a while for most content to be bloggified, when there is no content in the markdown body (or even just if it's less than some threshold), we should not show the previous/next lesson bar at the bottom of the page due to the redundancy with the one at the top.
• Don't show the updated date when there's only a video and no written content.

Include others in about page

The about page should have some mention of each contributor to the site, perhaps with links to their preferred pages.

Emotive Pi Characters

Today we were talking about the value of the pi characters for expressing emotion.

It would be really great to have one or more components that enable us to use the pi characters to communicate emotion and whimsy. In particular, we discussed two ways the pi characters might be used:

1. To personify footnotes that contain little side points. Not all footnotes would have pi characters, but some could. It's worth considering this while implementing any footnote funcitonality.
2. Used inline with the regular body text to emphasize an emotional point. For example:
   
   It would be cool for a pi character to make this exclamation.

Any component for these characters should definitely make it possible to specify the emotion of the pi character (as well as the associated text).

Print styles

Make sure lessons can be printed cleanly, e.g. with only still images, no interactive things like tooltips, even margins, etc. Do this at end when we have all the components we know we'll have.

Choose backend website hosting

GitHub pages is a free web hosting service that can host static things like images, html websites, etc. That's (so far) what we're using to host this website itself and its images/assets.

But we'll need more robust (paid) website hosting for other purposes:

1. GitHub pages could theoretically host all the lesson images and videos, but since it's free, there are storage limits that we'll likely run up against
2. We can't run more dynamic things on GitHub pages, like: hosting an email address, PHP scripts for email forms, Google Captcha services, etc.

Homework for Grant:

Find a website hosting service. I use Inmotion Hosting. Run your choices by me to make sure it has the functionality we'll need, but most popular services should be fine.

Basic components needed for lessons

• embed - actual youtube <iframe> embed
• figure - combination static/animated figure, with image url, video url, caption, start as image/video boolean, width/height specified
• question - multiple choice or fill in the blank question? params: question, different answers, correct answer, explanation?
• aside - way to show rich content on click or hover. implement as a tooltip (that allows mouse interaction) or accordion?
• mathjax - integrate properly
• table - style properly
• codeblocks - style properly

Figure component tweaks

Don't autoplay video until switch to that tab. Pause video when switching back to image tab.

Lesson comments section

Choose safe and reliable comment service, such as Disqus or some other service. Then paste its embed code into the comments.html include.

Probably want to wait until the site is live to do this so we don't get comments on the in progress site, and because the page urls (which the services hook into) will change (e.g. https://vincerubinetti.github.io/3Blue1Brown.com/lessons/test-lesson -> https://3blue1brown.com/lessons/test-lesson).

Next port dangling issues

• comment code more
• document components
• make sure all components have graceful failures when not enough params are provided. if required params not provided, just don't show component (instead of crashing!)

Remove normalize.css

Somehow normalize.css is being included in the GitHub Pages build, even though it is no where in my repo. It's screwing up some header and footer styles.

Patreon name list near lesson footer

Put list of Patreon supporters at bottom of each lesson. Those who contributed between a month leading up to the lesson's release?

Maybe pull from Patreon API? Or perhaps more simply, just make _data/patrons.yaml like:

# a supporter
- name: Adrienne Wilson
  start: 2020-10-24
  end: 2018-08-10
  star: true


# another supporter
...

Maybe have a special field for people who have supported > 1 year or high donation amounts, and highlight them in bold or gold or something?

Collapse header nav menu

Purge Git History

Now that our repository structure has settled down somewhat and #47 is almost done, I think it makes sense to purge our git history of big files. This will drastically reduce the overall size of the repo (currently ~42MB download).

Full admission, I also accidentally committed some large files to the repo when working with Git LFS, but it probably makes sense to do this anyways.

I used this script to generate a list of objects in the repo's history. For example, here are the largest 10 files in the history. Note, this list contains duplicate entries (same object id) when the file path was changed for an object.

100644 blob 831ebc200f6db517c090eccc4deada769ee08813 9882127	static/images/special/pi-fourier.mp4
100644 blob 831ebc200f6db517c090eccc4deada769ee08813 9882127	images/special/pi-fourier.mp4
100644 blob 0eb0c85d73c59292653314f82fd7802c4b5fc477 5051228	content/lessons/2021/git-lfs-test/animation-10.00-10.39.mp4
100644 blob 86983c9d0941a85963f6c2b523ad892eee059631  956891	static/images/store/short-3blue1brown-pi-plushie.png
100644 blob 86983c9d0941a85963f6c2b523ad892eee059631  956891	images/store/short-3blue1brown-pi-plushie.png
100644 blob dccdfc3f20f88b865172603c4aa69dc3e1dce540  804017	static/images/store/tall-3blue1brown-pi-plushie.png
100644 blob dccdfc3f20f88b865172603c4aa69dc3e1dce540  804017	images/store/tall-3blue1brown-pi-plushie.png
100644 blob c8268e87c9dfd5c891a42b946616fdb79cf58bc7  735316	static/images/store/fractal-curve-poster-set.png
100644 blob c8268e87c9dfd5c891a42b946616fdb79cf58bc7  735316	images/store/fractal-curve-poster-set.png
100644 blob 704c663661314540075925125d090f36058c5e08  733084	static/images/topics/differential-equations.jpg

See the full list here.

Suggested Method

I've used the BFG Repo Cleaner in the past to programmatically purge large files from a repo. Here are the steps for installing and using BFG.

Start by installing bfg.

brew install bfg

Clone a fresh copy of your repo, using the --mirror flag:

git clone --mirror https://github.com/3b1b/3Blue1Brown.com

Identify a size threshold to use when purging large files. For example, purging files above 1M would help quite a bit. @vincerubinetti should we use Git LFS to manage the images in the static directory?

bfg --strip-blobs-bigger-than 1M 3Blue1Brown.com.git

I think we can be pretty aggressive with the threshold, because BFG treats the files in the current commit as "sacred", meaning that it should only clean files from old commits. For example, running the command with a 1M threshold currently deletes the three files below:

Filename                    Git id           
---------------------------------------------
animation-10.00-10.39.mp4 | 0eb0c85d (4.8 MB)
pi-fourier.gif            | ef6a1192 (5.7 MB)
pi-fourier.mp4            | 831ebc20 (9.4 MB)

Then, update the history for the mirrored repository.

cd 3Blue1Brown.com.git
git reflog expire --expire=now --all && git gc --prune=now --aggressive

Check that the site still builds, the size and history of the mirrored repository. I think you could also compare the new list of objects sorted by size.

If this all looks good, push the changes.

git push

Afterwards, it is recommended that people ditch their old copies of the repo and make fresh clones.

Alternative: Remove Objects by ID

You can also remove objects by its id. For example, the pi-fourier.mp4 file has an object id of 831ebc200f6db517c090eccc4deada769ee08813

bfg --strip-blobs-with-ids <blob-ids-file>

Alternative: New Branch (Destructive)

A simple and really destructive method to make the repo is to create a new branch with an unrelated history and then delete the old branch.

Animate logo on hover

Make logo animate on hover/click, like this (source)

Rich link to other lesson component

Link to another lesson, with tooltip on hover that shows description or other metadata. Separating this from the basic components in #5 because I think the tooltip should/will look similar to what we do for the topic expansions on the homepage, which I will be doing next in a separate PR.

Search bar

Method to search site for content. Related: greenelab/lab-website-template#2

Probably just want to opt for an embedded google search. Grant will need to register/create a search console that we can paste into the template somewhere.

Link to credits' bios

Make the credits at the top of each post clickable. Link to bio pages for each author. Make new _members collection with bios like grant-sanderson.md, james-schloss.md, etc.

Automatically find corresponding bio in post layout.

Spotlight fixes

Pi creatures get covered up by video on small screens. Just remove.

Also per meeting on 5/9 we are getting rid of spotlight all together? Are we sure? Then there will be nothing directly watchable on the homepage.

group lesson folders by year instead of topic