unicorn-utterances/unicorn-utterances

🦄 Practice programming with magically majestic methods

Unicorn Utterances Website

This repository acts as the source code location for the Unicorn Utterances blog.

Sponsors

We disclose every sponsorship we share openly on GitHub

Statement of Ethics

We never want to end up in a place where our educational content, experience, or community is compromised by either financial sway or potentially harmful members of the community. As such, we've implemented the Contributor Covenant as our code of conduct to uphold these values.

We also pledge to maintain transparency in regards to any finances that flow through the project. Not every sponsorship contains a financial contribution, but if one does we will disclose both what those finances are going towards and what will be done in exchange.

Contributing

We highly encourage and celebrate others contributing to our site and our community! We've written a comprehensive guide on how to do so here. This guide includes instructions for how to add a new post to the site, how to edit our code, and what our deployment strategy is.

Keep in mind that we request developers reach out via our Discord or via GitHub issue before extensive development is pursued. If you have a feature you'd like to add to the site, let us know! We'd love to do some brainstorming before coding begins!

We extend this invitation to those who may be unfamiliar with our processes. Be sure to check out our CONTRIBUTING.md file first, but don't be afraid to join in and ask questions if you're uncertain of anything

unicorn-utterances's Issues

Count inline code in word count

Currently, of you make a blog post that's:

Hello, world

Our word count will only show 1 word

As a result, I've built a plug-in in the fix-count branch to fix this.

However, that work is blocked by a bug in Gatsby:

gatsbyjs/gatsby#20684

Update all references to new repo name

Enable auto-tagging editors to a post

Just as we're able to auto-assign roles for an author based on frontmatter tagging, I would also like to be able to auto-assign the role of "editor" on folks who are not the author but make commits for a post.

The way I would like to do this is by building out a gatsby plugin that provides git data from the repo itself into the GraphQL. This would also add fields for File and MarkdownRemark nodes. Due to the required research phase/etc I am going to assign myself to this

Some questions that need to be solved for:

• If we do want to use direct local git repo info, what library do we want to use to get the git info on a file?
• How would we track the user's git info? (a commit contains an email that might not be associated with a user)

We might be able to solve some of this just by using GH API v4:

query {
  repository(owner: "unicorn-utterances", name: "unicorn-utterances") {
    ref(qualifiedName: "integration") {
      target {
        ... on Commit {
          history {
            pageInfo {
              hasNextPage
              endCursor
            }
            edges {
              node {
                author {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

https://developer.github.com/v4/explorer/

But then the questions are:

• How do we handle the GH API auth call?
• When do we query that data?
  • And do we mock it util then?
• Do we really want to limit ourselves as an org to be reliant upon GH's APIs?
  • How does this potentially align/affect our goal to have self-rolled auth long-term?

At this stage, I think there's a lot of questions to be had, but it's good to get them down for now

Enable generation of full-text license file on a per-author/license basis

While we currently (#32 ) have the ability to display a license at the bottom of a post, we do not currently have a license file generated for that author and the license for that file. This seems like an oversight we could solve fairly easily.

My suggested API would be the following:

In our licenses.json file, we add a "copy" property that includes a reference to a file of the full text of the license in question.

This file will include interpolation compatability to fill it with the frontmatter.author properties to fill the text of that license on compile-time (using onPostBuild or something like it) and create a consistent URL structure for such (ala unicorn-utterances.com/licenses/crutchcorn--cc-by-nc-sa-4.md).

For future development, we could potentially even introduce 301 redirects using our NGINX rules for each of the posts to make https://unicorn-utterances.com/posts/uttering-hello-introduction-post/LICENCE.md redirect to the expected license

Generic profile links

The current unicorn structure only supports links for "socials", such as Twitter or GitHub. I'd like for this to support generic links of all types, such as personal websites, Mastodon or other fediverse accounts, LinkedIn profiles, GitLab accounts, etc. - but that list would just keep growing.

Rather than support all kinds of links in this field, it might be better to treat it as an array of links which can have either a specific or generic type associated with them (which is then used to determine the icon / other future uses in the site).

I do agree that the number of links should be limited in some way to preserve the style of the profile layout, but the type of links that can be included should not be restricted by it. While Twitter/GitHub are often used for their purposes, I don't think that this project should specifically endorse their use over competing platforms, nor should it prevent people without those platforms from taking advantage of this functionality.

Proposed example:

{
    "links": [
        { "type": "twitter", "at": "fennifith" },
        { "type": "website", "name": "Personal Site", "url": "https://jfenn.me/" }
    ]
}

Possible link types that could be added (that aren't possible with the current structure):

• website (for generic "links" that might not mean anything)
• profile (for abstract social media links or portfolios)
• fediverse (federated blogs or social media under an acknowledged protocol)
• mastodon (mastodon servers / accounts)

Internationalization and translations

We need to have a way to translate both the site strings and the posts themselves. I suggest we follow the example of @gaearon and utilize a similar setup to his:

https://github.com/gaearon/overreacted.io#contributing-translations

Fix post order in author post list

Currently, our posts are sorted backwards for authors pages. We're able to fix this by adding a sort to the GraphQL called made in the author page component

a046f1e

However, this breaks develop mode (tracked here: gatsbyjs/gatsby#16446)

We're just waiting for upstream, then this branch can be merged

Auto-deploy on push to master using webhooks

We currently manually deploy from master whenever a PR is made. However, due to our stringent policies regarding master PR merges, we could likely enable this functionality using webhooks

Add table of contents for blog posts

It would be great to have a table of contents off to the side on desktop

Design from @tommyemo

A question that I have is what we'd have for mobile. I think a dropdown in the header area might be nice - but I'm overall unsure where this would go for now. Initial version should likely be desktop only for now.

Should use the gatsby-transformer-remarked plugin's tableOfContents

Oswald font isn't fetched by gatsby-plugin-prefetch-google-fonts

See: escaladesports/legacy-gatsby-plugin-prefetch-google-fonts#27

Possibly fork the package or use an existing fork if no replacement is found. Archivo looks nice for now.

Add an about us page

Designs provided by @tommyemo

Integration merge 03/02/20

Whoops. Wrong tab

Migrate to Gatsby 3

https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/

Back button should take user to previous page instead of homepage in some situations

Currently the back button is hardcoded to route the user back to the homepage which definitely makes sense for things like blog posts, but when going from homepage --> about page/blog post --> unicorn page, the back button there should return the user to the previous page they were on instead of the homepage.

Add steps to make a PR to Tweet out a promo when a post is merged into master

Currently, we have a way to tweet from the official Unicorn Utterances twitter page via:
https://github.com/unicorn-utterances/social-media-posts

I think it would be great to foster a much more open community by adding into the contributing guide (which should probably be broken into a CONTRIBUTING.md file with this change) a way to make a PR in order to Tweet out the announcement for the new post

Migrate to NextJS Static Export and GraphQL

As #70 is the issue in order to track the progress of migrating from compile-time render to NextJS SSR, I think a better stepping stone ticket between those two is to build out a local GraphQL server that assists in NextJS static export.

This static export should built at compile-time, similarly to how Gatsby works currently.

An example of this can be found at:
https://itnext.io/next-js-export-w-a-coupled-express-apollo-server-a7a4b4bc4f25
https://gist.github.com/OutThisLife/587f6fc89f72fc3345b1d44880c8ae70

/posts child routes 301 to root

Although the Link component is nice for enabling the pages to load in-place and transition smoothly, it seems that they only function with JS enabled. Additionally, it is not possible to link directly to a post, as it redirects to the homepage. For example, this link should go to the "Uttering Hello" post but instead only goes to the homepage. Although JS will inevitably be required for some functionality, this seems like something that should work without it.

Google TalkBack accessibility issues

Google TalkBack on Android v10 and Chrome v81 Dev with the default navigation setting:

• Reads the following as use attributes
  • Is this an upstream bug or can this be patched on our side?

[use `data` attributes](http://example.com)

• Reads the filter select tool in a very verbose manner
  • What's the intended behavior for this?

Alphabetize the about us page

While entirely unintentional, we've ended up with the about us screen being placed in the same order of folks in the unicorns.json file.

In order to keep things non-biased and equal, I think it'd be a good idea to alphabetize them with a GraphQL sort (so we don't have to force new PRs to worry about this)

Add staging environment that auto-deploys when push to integration

Similar to #74, it would be nice to have a beta.unicorn-utterances.com that would enable us to have a staging environment for our integration branch that uses webhooks to deploy

Add user auth to the site

One of our long-term goals as a team is to enable users to have a more custom tailored experience in learning CS content. Adding user authentication will enable a lot of functionality that aligns well with our interactive user-driven dream

We'll need to figure out:

• What do we want/need for privacy sakes?
  • Have an explicit clear verbose outline that complies with GDPR and is well understood
• What security do we want/need to have to keep our user data safe?
  • How do we handle security info issues?
• What type of initial user portal do we want to have
  • Design
  • Functionality
• How do we migrate current users?
• Should we allow OAuth?
  • Should this OAuth data include profile pictures/etc that we should use as user data?
• How do we want to build out the server?
  • What language and stack do we want for the server?
  • Do we want NoSQL or SQL?
  • Where/how do we want to deploy?

We'll need to break out the tickets when we've had further discussion on this ticket, feedback encouraged

Blocked by: #70

Make header sticky

In the original designs, we wanted to have the header be sticky. This is still the case but was cut due to time constraints.

I would love this to animate down with a fade after the user scrolls past the header

Switch to an in-house or otherwise more reputable comments system

This blog post is a start on reasons not to use Disqus, but I'll sum up a few of the vital points:

• it absolutely murders the page's overall load time
• the blocky and (IMO) subpar design doesn't match the rest of the site
• the site (and its users) are inhibited by Disqus's privacy policy
  • What this means for end users is that there is no way to ensure that their identifying data or usage information is not collected (short of blocking disqus.com with a browser extension, like I have done - though others might not have the time or knowledge necessary to do so).
  • Disqus's privacy policy states that they can collect and share aggregated statistical or demographic data for any purpose. They can (and probably do) also collect identifying data such as IP addresses and "unique Cookie ID" regardless of whether the user actually interacts with the comments widget or not. This leads me to believe that they are building a profile on every user that touches a site with their comments widget in, for the purpose of targeted advertising and other marketing techniques that privacy advocates commonly disapprove of.

I believe we could create a faster, more convenient, and frankly just better user experience with our own comments system, or maybe using an existing project that we can self-host - but the end result is that we (who I hope are a trustworthy party) are in control of the user data, and not a company that profits from selling it.

Fix homepage logo margin on small breakpoint

On the homepage, the logo has unnecessary margin-right on small breakpoint. That should be fixed.

Add dark mode

In the src/assets/icons directory, we have a dark and light icons that were designed for the site. This feature was cut due to time, but having in toggle in the top right of the header (#3) would make for a better reading experience for users that prefer a dark mode

Because we're using CSS variables, this should be relatively straightforward

Inline code does not force wrap

The CSS should be adjusted for inline code to prevent the document size to shrink on small viewports.

Reproduction:

• Visit https://unicorn-utterances.com/posts/integrating-android-code-in-unity/#manifest-file
• Emulate a small viewport (e.g. iPhone SE)

Screenshot of repro

Related Google Search Console issues

Inconsistent spacing between search bar and filter dropdown

Taking a close look, I noticed that the search bar is 8px away from the post below it (including borders) but the filter dropdown across from it is only 6px away. Although this isn't a huge deal, it would be nice to fix it.

Write tests for the site

We currently have an initial setup of jest present, but we are not actually running tests. We should use both jest as well as these:

https://github.com/testing-library/jest-dom
https://github.com/testing-library/react-testing-library

For more docs see:

https://www.gatsbyjs.org/docs/testing/

Allow a post to have multiple authors

Considering the collaborative nature of this project, I'm sure that there will be some blog posts written by more than 1 person. At the moment it only seems to be possible for there to be a single author on a post, so it would be nice if the post format could have a list of authors instead. We will need to consider the UI for this as having multiple profile pictures on the homepage wouldn't work very well at the moment.

Style guide and linting markdown

Our markdown (among other things) has lots of spaces instead of tabs. And because of our decision to use tabs for accessibility, we should update our existing code base and add a markdown linter.

And adding a style guide may also be nice to inform contributors of the style rules that aren't linted.

Defer rendering dark mode transition until after page fully loads

Due to using compile-time SSR, we are unable to tell what theme the user wants to load when the user requests the page. As such. we ship light theme to the user by default. However, with our current code, when the user loads the page - it will quickly do a check against localstorage and flash the dark mode in a jarring way if the user last selected dark mode.

@adueppen suggested a solution to make this experience a bit better as an interim - defer the page transition/check until AFTER the page is loaded.

To do this, we could use a combination of useEffect (as it runs AFTER the SSR) and setTimeout (which will defer the call to the end of the event-loop) to defer the loading of this call until after the initial load to make a more smooth transition on initial page load

Full results of search do not match

Searching for "freenod", "free", etc comes up with the freenode IRC posts, but searching for "freenode" comes up with no results. Similarly, "introduct" comes up with 2 articles with "introduction" in their names, but as soon as any of the last 3 letters are added it finds nothing. This will need some more testing to figure out the root cause.

Respect OS theme for light/dark mode toggle initial value

We currently use a default initial value for light/dark mode when the user first loads the site. What we should do is respect the value set by the OS with prefers-color-scheme:

https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

There is a side problem where the JS currently will set the initial value to localStorage and then try to reload it. Here's my thought process on how this functionality should behave:

Always respect prefers-color-scheme UNTIL the user toggles it manually. THEN, if the user toggles it manually, save that value to localStorage. Also save the value prefers-color-scheme was set to when that manual toggle was run to localStorage.

When the page is refreshed, check the prefers-color-scheme that was saved to localStorage, if it matches what the current value is (or there is no value saved to localStorage because it was never manually toggled - go ahead and check if the user manually set a value to localStorage (by toggling) and set that value to dark mode

However, if the localStorage saved prefers-color-scheme does NOT match the current prefers-color-scheme value, clear the localStorage (clearing the user selection and the previously saved prefers-color-scheme value, and just respect the current prefers-color-scheme value

Of course, because Gatsby is (compile-time) SSR'd, we'll need to make sure that these checks run within a useEffect loop/related so it runs during the client render

Add support for various licenses to be added to individual posts

• Define a structure for LICENCE.md to be placed in a file (or a frontmatter field?)
• If not using frontmater field, add the LICENCE.md to the GraphQL calls for Unicorn Utterances
• Provide a default licence? (@fennifith what do you think? @evelynhathaway do you know of any reason legally we couldn't/shouldn't do this? I don't know if we should, seeing as one could accidentally commit a post and that way we can CI to force a check for a LICENCE.md file and remove legal ambiguity) NOT DOING, SEE BELOW
• Mention the licence layout in README.md
• Include an image of that licence in the bottom or have a sidebar with info @tommyemo would love some thoughts on a design for this. I don't know what would look better or where things would go

Use cookie to request SSR render of proper dark mode setting

Once we implement SSR (#70), we want a way to properly SSR the theme the user has selected by using a cookie (either alongside or replacing our localstorage method of keeping preferences - I know cookies have some weird timing stuff) to send initial data to the server

This idea was thought of by @evelynhathaway and is a great way to implement this functionality before #71 is implemented to replace this functionality

Worth mentioning: Just because #69 would be overwritten by this work does not mean it should be defered. Let's do that one before this

Blocked by: #70

Make filter dropdown code generalized

While work on this was started in terms of making the a11y code hooks based, it was never finished.

I should be able to have a dropdown button that will resize based on the "button"'s text size/etc without having to have it be marked as an aria-listbox

Use GitHub actions for CI

We're currently using TravisCI, it would be nice to switch to GitHub actions for our current CI setup to keep things centralized

"Author" role is duplicated on about page soft-load

If the about page is navigated to multiple times without a hard reload, the "author" role on contributors will be duplicated infinitely.

Treat external links from blog posts as `rel="nofollow"`

@evelynhathaway pointed out that we should be using nofollow for our blog post external links for SEO/page structure purposes.

We should be able to do so by using the following plugin:

https://github.com/remarkjs/remark-external-links

Fix linting warnings present when running `npm run develop`

Due to an upgrade of React (alongside some malpractices of hooks applied by myself), we've ended up with various warnings regarding how hooks (and other areas) are being used. It would be great if we could get these warnings to silence by fixing those problem areas

Switch to Next.JS SSR rather than compile-time render

We're finding more and more usecases where we'd want to do things with non-compile-time SSR. It aligns much better with our long-term goals and use-cases and as a result would be worth the engineering offset

For our initial developmental effort, we could have a small Node express app that enables us to still load data from our Markdown and JSON files to present a very similar dev experience to what we have now:

https://graphql.org/code/#express-graphql-graphql-js-running-an-express-graphql-server-github-https-github-com-graphql-express-graphql-npm-https-www-npmjs-com-package-express-graphql

Luckily, because of the nature of Gatsby plugins, it would be relatively trivial to lookup how they're doing it and either:

1. Provide a compat layer between our custom NextJS instance

I like this idea a lot personally, it wouldn't be too bad to run the lifecycles in the same expected lifecycle methods

There may be some problems matching up lifecycle methods due to the lack of compile-time SSR, but that'll be something we'll have to engineer around and discuss at the time (plus, we can probably have an overwrite to what lifecycle method things run at)

2. Port their plugins to be entirely in-house

While this would be much faster, likely, it would be bad due to note contributing back to the broader community, duplicating dev effort, etc

This will need to be a larger discussion from a technical perspective, feedback encouraged. Once a path forward is more standardized, we can break this ticket out to further other tickets to break out the developmental efforts

Potentially impacted by this: #65, #60

Add functioning share post buton

We have, in code, the start of a share post button in the footer of a post. We wanted to base the styling off of #2 for the dropdown. Work should be done to enable sharing directly to Twitter, Facebook, and others that might be wanted

Add support for files to be attached to posts

One of the features that I'd love to have for the site is the ability to attach "arbitrary" files to the post. This would enable authors to attach talk slides to related posts, zips of assets, etc.

Because the styling is so similar, work should be done on #2 before work on this issue

Filter button is deceptively small on mobile

At small screen widths, the filter button appears to take up the entire width of the screen, but it can only be activated by clicking/tapping on the icon and/or text. The search bar similarly expands to the width of the screen, but it does not have this issue.

Enable local code samples

As we are an organization, we want to make sure to avoid having code examples locked behind a walled-private account/service. Using the following plugin we can track all of our examples locally:

https://www.gatsbyjs.org/packages/gatsby-remark-code-repls/?=code

Make profile links open in a new window or tab

As they're external links, they should likely have target="_blank"

Add discord to README

Only the first author is sent to SEO component

It seems that during our migration to support multiple authors, we did not do our due diligence in migrating the SEO component to support multiple authors. We should fix this

Hide components that require JS in SSR

Currently, components such as the theme switch button, filter/search, etc that require JS to function still appear on the SSR'd version of the website. Ideally those components should only be rendered when it can be confirmed that JS is available on the client.

Add the site to Gatsby's site showcase

While this PR is not in this repo, it would be nice to do

https://www.gatsbyjs.org/contributing/site-showcase-submissions/

If this is picked up, please link the associated Gatsby PR