Swizec Teller - a geek with a hatswizec.com

    Livecoding Recap 48- Why contributing to big opensource projects is still hard

    This is a Livecoding Recap – an almost-weekly post about interesting things discovered while livecoding. Usually shorter than 500 words. Often with pictures. Livecoding happens almost every Sunday at 2pm PDT on multiple channels. You should follow My Youtube channel to catch me live.

    GatsbyJS has a bugfeature that I don't like and I'm gonna fix it! Biggest opensource project since I poked around phpBB back in high school.

    I can do this!

    image photos 8500000 Single Ladies single ladies 8586971 424 550

    GatsbyJS is a React-based static site generator. The reason I'm so invested is because almost everything I build with React is a static site. Landing pages, single data visualizations, stuff like that. All static.

    Gatsby has a plugin, gatsby-transformer-remark, that lets you write copy-focused pages in Markdown. React gets tedious when you want to focus on writing copy.

    This remark transformer comes with a feature I love: tableOfContents. Looks at your header tags and generates a table of contents. Great for making your site easier to navigate.

    But there's a problem.

    Table of contents uses only hash links like #this-is-a-subheading. This works great when it's on the same page as your content, but it’s not so great when you put it on an index page.

    Index pages are often at different URLs than their content pages. So when you try to link with just a hash, it doesn't go anywhere.

    I decided to fix that and use absolute links.

    So we looked at the CONTRIBUTING.md doc in Gatsby's repository, and it was wonderful. Tells you everything you need to set up a development environment so you can work on Gatsby and your test site immediately picks up on it.

    1. Fork and clone Gatsby ✅
    2. Run yarn run bootstrap

    Wait… no… that didn't work. Step 2 and we're already blocked. 😭

    We filed a helpful issue complaining that nothing works and everything is broken. The command didn't run through, dependencies were missing, and everything blew up in our face.

    2 hours later, we had installed some 30 missing packages and aaaaalmost got a clean yarn test run. Very important to have all your tests passing before you start poking around a large codebase.

    A very helpful person named m-allanson saved our asses. They found a commit from Gatsby's head maintaner that changed something in a config – removed yarn workspaces whatever the hell that is – and was just 23 hours old.

    All our troubles were because of a commit from less than a day ago. Talk about timing!

    And it was the kind of problem only a new contributor could discover. Everything worked for people who had stuff installed from before.

    So… yay? We helped?

    Once we got up and running, it was almost time to stop livecoding for the day. We had just enough time to figure out where in the code we're going to have to fix those links.

    A file called gatsby-transformer-remark/srcextend-node-type.js.

    This function 👇

    async function getTableOfContents(markdownNode) {
    const cachedToc = await cache.get(tableOfContentsCacheKey(markdownNode));
    //if (cachedToc) {
    // return cachedToc
    //} else {
    const ast = await getAST(markdownNode);
    const tocAst = mdastToToc(ast);
    let toc;
    if (tocAst.map) {
    //toc = hastToHTML(toHAST(tocAst.map))
    toc = toHAST(tocAst.map);
    console.log(require("util").inspect(tocAst.map, false, null));
    } else {
    toc = ``;
    }
    cache.set(tableOfContentsCacheKey(markdownNode), toc);
    return toc;
    //}
    }

    Note the console.log. That's where we have to hook into the toc abstract syntax tree and change the links.

    Not sure how yet, but how hard can it be 🤔

    Did you enjoy this article?

    Published on October 9th, 2017 in Livecoding, Technical,

    Learned something new?
    Read more Software Engineering Lessons from Production

    I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.

    Subscribe below 👇

    Software Engineering Lessons from Production

    Join Swizec's Newsletter and get insightful emails 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.

    "Man, love your simple writing! Yours is the only newsletter I open and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"

    ~ Ashish Kumar

    Join 15,883+ engineers learning lessons from my "raw and honest from the heart" emails.

    ⭐️⭐️⭐️⭐️✨
    4.5 stars average rating

    Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.

    Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.

    Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.

    Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev

    Want to Stop copy pasting D3 examples and create data visualizations of your own? Learn how to build scalable dataviz React components your whole team can understand with React for Data Visualization

    Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections

    Want to brush up on modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com

    Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog

    Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet: es6cheatsheet.com

    By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️

    Created by Swizec with ❤️