/yakcollective

Home page of the Yak Collective projects

Primary LanguageHTML

  • Netlify Status

  • When updating this document, please make sure to keep the Roam page and site README.md file in sync!

    • The easiest way to do this is to make updates in Roam, Export the page as Markdown using the "three dots" overflow menu in the upper right, and then overwrite README.md with the contents of that file.

  • Last updated June 21, 2020 by [[Nathan Acks]].

  • Contributing

    bundle config set path vendor/bundle bundle install bundle exec jekyll build - When doing local development, you may want to run bundle exec jekyll serve instead to fire up Jekyll's local server mode so that you can connect to http://localhost:4000 and browse the current version of the site. - Netlify will rebuild the site automatically whenever changes are pushed to the repo and/or merged in.

              - **Warning!** Netlify's build environment uses UTC, so when using `site.time` to mask pages (which we do sometimes), be aware that they will become unmasked relative to UTC!

    • Related Projects

      • [[Yak Talk Newsletter – To Do and Content Ideas]]

  • Site Structure

    • Here's a quick rundown of the moving parts...

    • Pages

      • about.md
      • index.md
      • members.md
      • projects.md
      • writings/feed.json
      • writings/feed..xml
        • RSS feed, equivalent to writings/feed.json.
      • writings/index.html

    • Assets

      • assets/*
      • robots.txt

    • Collections

      • members
        • Member data, one person per file. Referenced by projects and posts.
      • projects
        • Yak Collective projects.
      • sequences
        • Sequences used to group projects. Projects are counted in "days released since X".

    • Member Feeds

      • Posts in writings/_posts and newsletter/_posts are auto-pushed from member RSS feeds using IFTTT and Netlify Functions.
      • Current feeds pulled are documented above in "Member RSS Feeds". To add or update a member feed, please open a ticket.
      • Relevant infrastructure bits:
        • packages.json
        • functions/create-post.js

    • Templates

      • _layouts/default.html
        • Base layout. This isn't actually used on any pages, but is inherited by other layouts.
      • _layouts/member.html
        • Used for member pages.
      • _layouts/member-list.html
        • Used for the member list page (members.md).
      • _layouts/minimal.html
        • The most minimal layout used on yakcollective.org. Directly used on the site home page (index.md), and inherited by most other layouts (with the exception of project.html).
      • _layouts/page.html
        • Normal layout for stand-alone pages.
      • _layouts/post.html
        • Layout for posts. Every post is assumed to have an author defined in the members collection.
        • Note that while post pages are generated as part of the build process, they are not linked anywhere on the site itself. (Links that would point to them instead point to the original post on the member's website.)
      • _layouts/project.html
        • Fancier formatting for pages in the projects collection.
      • _layouts/project-list.html
        • Used for the project list page (projects.md).

    • Shared Elements

      • _includes/analytics.html
        • Google Analytics code; included on all pages by proxy through _layouts/default.html.
      • _includes/footer.html
        • Page footer elements.
      • _includes/head.html
        • HTML <head/> elements (things like <meta/> tags, not page headers).
      • _includes/page.css
        • CSS used for per-page customization (accent colors, hero images, etc.).
      • _includes/member-card-html
        • Reusable "member card" element, currently used in the members list, individual member pages, and in the _layouts/post.html template.
      • _includes/nav.html
        • Page navigation elements.
      • _includes/project-box.html
        • Project card, used in the projects list and individual member pages.
      • _includes/toc.html
        • Table of contents for _layouts/page.html elements. Does unreal things with Liquid. Probably black magic.

    • Build Infrastructure

      • Repo

        • admin/*
        • _config.yml
        • Gemfile
        • Gemfile.lock
        • netlify.toml
          • Various Netlify build directives, just redirects right now.

      • Secrets

        • Netlify CMS uses GitHub as an OAuth provider; connection secrets can be found in Netlify under Settings > Access control > OAuth.
        • The create-post function stores configuration information, a GitHub access token, and a token used to authenticate incoming requests in Netlify under Settings > Build & deploy > Environment > Environment variables.

  • Site History

    • Notes for v1.0 and v.20 adapted from the June 13, 2020 #infrastructure chat notes.

    • v1.0

    • v2.0

      • Built by [[Nathan Acks]].
      • More flexible (and hopefully easier to maintain!).

      • Major Changes

        • Documentation (originally just in the GitHub README.md, now this file!).
        • Uses Netlify to build and serve the site, with code still stored in GitHub.
          • Still using Jekyll as the build system.
        • More consistent visual language (consistent link colors, concept of "accent" colors, etc.).
        • Lots of changes around projects and the project page.
          • Projects are part of a "sequence" indexed off of a particular date. Currently there's only a COVID-19 sequence (a.k.a. "pandemic mean time"), but others can be added.
          • Project cards are customized with the project hero image and accent color.
          • Three sections:
            • Latest Projects are the most recent (live) three projects.
            • Upcoming Projects are projects that are on-deck and we want to advertise, but aren't yet released. These project cards are not clickable links, and the project page itself is not built.
            • Past Projects are all live projects older than the most recent three.
          • Hero images on individual project pages are now faded a bit to improve readability.
          • Lots more flexibility with individual project pages now.
            • Custom hero image, accent color, CSS.
            • We'll keep evolving this page as we need more flexibility. About 60% of the code was rewritten for The New Old Home; subsequent projects will probably also need new/changed code, but the aim is to need to make fewer changes each time.
        • Member pages are intended to function as "landing pages" for Yak Collective folks.
          • The Members page proper arranges people by join date (defined as "first project contributed to"), then alphabetically within each cohort.
            • Cards are clickable links to the member page itself.
          • Members pages are linked on each project page.
          • Each member page includes:
            • Projects (as project cards) that the member has lead or collaborated on.
            • Blog posts/writings from RSS feeds (when available).
            • Each member can also include additional descriptive page text (though this isn't currently being used by anyone).
        • The Join page is just a wrapper around the existing Google Form.
          • Using a wrapper means we can swap out the Google Form for something more sophisticated later.
            • Right now, there's an unused "welcome" page that could be used for a landing page after form submission.
        • Netlify Functions (which allows Amazon Lambda functions to be deployed as part of building the site) are used to commit incoming member blog posts into the site GitHub repository.
          • The commit causes the site to be rebuilt by Netlify, which adds a link to the blog post to the Writings page.
          • Post contents are cached in the GitHub repo to allow us to speed up site builds, allow posts that have disappeared from member RSS feeds to still be linked, and to allow for later experiments around textual analysis, auto-tagging, etc.
          • Posts are always linked back to the original, never internally. The point is to push people to member sites rather than trying to get them to stay on our site.
          • Similarly, the writings RSS feed is styled after Daring Fireball: Post content is displayed, but links take people back to the member's site, not yakcollective.org.
        • There's an experimental admin page built using Netlify CMS.
          • This isn't working right now for folks who don't have access to the repo. See GitHub issue #10.
            • Should work for anyone with a GitHub account.
          • Edits should create pull requests, that can then be approved.
          • Preview doesn't capture the whole look of the finale page right now.
            • This can't be supported with Jekyll, but may be possible to support by moving to Gatsby (see GitHub issue #12)