Forem: Sam Robbins

Adding captions to images in MDX

Sam Robbins — Sun, 19 Sep 2021 18:41:53 +0000

Using MDX you can overwrite the default components that are provided by Markdown. In this blog I will use this to add captions to images.

The first thing to do is to look at the table of components for MDX, and here we can see that images are represented by img. By following the link we can see the markdown

![alpha](https://example.com/favicon.ico "bravo")

Yields the following items

{
  type: 'image',
  url: 'https://example.com/favicon.ico',
  title: 'bravo',
  alt: 'alpha'
}

To adapt this component, we are going to use title as the caption

Then we create a React component, where each of the keys are passed inside props

function MyImg(props) {
  if (props.title !== undefined) {
    return (
      <figure>
        <img src={props.src} alt={props.alt} />
        <figcaption>{props.title}</figcaption>
      </figure>
    );
  } else {
    return <img src={props.src} alt={props.alt} />;
  }
}

A conditional statement is used here so that no excess formatting is introduced if no title is present. The standard figure layout is used as a tag is there specifically for captions

You can then pass this component to MDX in the method detailed here and the captions should not display themselves. You can then apply CSS or classes to the HTML tags in order to style it as you want.

Prevent a Vercel site from being indexed in search engines

Sam Robbins — Sun, 19 Sep 2021 18:39:25 +0000

There are cases in which you won't want a site to be indexed. For me, this was because I have a previous version of my portfolio website available as a template, and that outdated template was coming up when searching about me because I included some information about me.

To solve this problem, the x-robots-tag is provided, which allows you to specify if you want your site to be visible on search engines. This tag is to be set as an HTTP header from requests made to the website, and this is made easy in Vercel, you can read more about all the headers here, and how to implement them here. In my case, I want the whole site to not be indexed, and so I want a source pattern that covers the whole site, for Vercel this pattern is /(.*).

There are a range of options for the x-robots-tag, I'm going to choose noindex, which will ensure that any of the pages on the site won't be indexed, however links from the site to other sites will be indexed. This is fine for me as it means that social links will be indexed and things like that, however if you don't want any indexing to happen, you can use none.

Now to the actual implementation, you want to create a vercel.json file if you don't have one already, and add

{
  "headers":[
    {
      "source": "/(.*)",
      "headers" : [
        {
          "key" : "x-robots-tag",
          "value" : "noindex"
        }
      ]
    }
  ],
}

If you already have a vercel.json file, ignore the outer braces, and just add the headers key inside your object.

Your site should redeploy on changing this file, and once it has deployed, then you can run

curl -I [url]

Replacing [url] with whatever the domain you don't want indexing is. This will give you a big list of properties, the one you're looking for is x-robots-tag, and it should be whatever you have set it to

My new portfolio website

Sam Robbins — Wed, 30 Dec 2020 13:11:02 +0000

What I built

I rebuilt my portfolio website using the latest technologies to increase performance and user experience.

Category Submission:

Personal Site/Portfolio

App Link

https://nextjs-portfolio-pb6dr.ondigitalocean.app/

Screenshots

Description

This site serves as a summary of me online, containing all my skills and experience, along with showing my portfolio projects. In addition, there is also space for a blog and long form writing.

Link to Source Code

https://github.com/samrobbins85/portfolio-website-v3

Permissive License

MIT

Background

I love working on my portfolio website, and it was working well with Hugo, but there were a lot of features of frameworks like Next.js that I wanted to use. This was a great opportunity to rewrite it, allowing for more development in the future.

How I built it

For this I used the digital ocean web service from the app platform. This allows me to run a server, which is used for optimizing the images before sending them to the client.

This was my first time using Framer Motion, which I used for the animations on the portfolio page. I'm very impressed by its functionality and look forward to learning more about it.

This was also my first website that I've built with a CMS, choosing GraphCMS as it had all the features I needed. However, during building the website I learned more about what I want from a CMS, so I may change the CMS in the near future.

Next.js and Tailwind CSS have been part of my tech stack for a while now, and I love using them. Next.js was particularly useful in providing getStaticProps for fetching all the data from the CMS, and the Image component, which allows for optimized images, and eliminates layout shift, which will be important in the next year as Google SEO starts to prioritize sites with good core web vitals.

I expanded my use of Tailwind CSS for this project by building my first Tailwind CSS plugin. This plugin brings the design ideas from LaTeX.css to Tailwind. You can see this being used on the writing page of the website. If you want to use the plugin, you can find it on npm.

A new package from Tailwind Labs is Headless UI, this makes it easy to produce accessible UIs in a range of frameworks and to style them with Tailwind. This has been used in a small subsection of the portfolio pages where there are multiple GitHub repositories for a single project, so I have a dropdown to list them all. Looking like this:

Next.js vs Gatsby for a portfolio website

Sam Robbins — Tue, 29 Dec 2020 10:21:24 +0000

When choosing a React static site generator, there are two major choices, Gatsby and Next.js, with fairly different approaches.

Advantages of Gatsby

Plugins. Gatsby has a huge range of plugins to make things simpler, including connections to CMSs and markdown processing.

Image component. Both frameworks now have an image component, but Gatsby has had one for much longer and so has had time to make it better.

Advantages of Next.js

I already know it. Obviously this one won't apply to everyone, but there's a big advantage to just choosing the framework you're most familiar with as there's no learning curve.

Increased flexibility. Gatsby is very much about "The Gatsby way of building", providing a range of systems in which you can build your app, whereas Next.js is more like an extension of Create React App, making it easier to build a wider variety of applications. Next.js also provides opportunities for having a backend through getServerSideProps and their API routes should I ever need to use it.

Development experience. Gatsby takes a lot longer to start the development server, which makes developing using it a somewhat painful experience on larger or more complex sites.

Links with companies to optimize performance. As the most popular React framework, Next.js has seen contribution from Google and Facebook, using Next.js as the testing ground for new features.

Conclusion

Overall, I decided to go with Next.js for my new site, and so far I'm very happy with my choice. Both solutions are good however, and you can't really go wrong either way.

Moving away from Hugo

Sam Robbins — Fri, 18 Dec 2020 19:38:17 +0000

As part of the Digital Ocean App Platform Hackathon I am going to remake my Portfolio website. The question here is why, when I have an existing portfolio website that does its job?

There are many reasons for this, but first I'll go over why I love my current setup

Why Hugo is great

Hugo is really really fast, it does in milliseconds what will take other static site generators minutes. This means that I never need to worry about how long my build will take, and so the content is updated as fast as possible.

Hugo is already set up to be a blogging platform, there is built in support to mark files as drafts and so not publish them. You also don't need to add any boilerplate code to get up and running with a blog format where you have a page of all the blogs and lots of blog pages.

Why I might want to move from Hugo

I can use a CMS, this gives a better authoring experience than what is possible with Hugo. I currently use Forestry as a CMS for Hugo, but due to it being git based rather than API based, there is a limit to the features it can provide. An example of this is when adding technologies to my portfolio projects, I have to manually set up the technology each time with title, image and link, whereas with an API based CMS I can predefine the technologies and just include them with one click.

I can use React, I'm thinking of moving away to a React based static site generator. This provides an advantage as I don't need to manually include Alpine.js which I currently use for the interactivity and React provides a greater range of features. I can also use React libraries such as Framer Motion to provide animation on the website.

Greater flexibility, Hugo is great at doing what it is designed to do, but I was already somewhat stretching the use case for Hugo with single pages beyond the index page. In comparison, React based static site generators are just frameworks for single page apps, and I can make whatever I want with them.

Making an NPM package for a React component library with Tailwind CSS

Sam Robbins — Sun, 06 Dec 2020 13:07:56 +0000

First you need to make an npm package, this can be done with npm init provided you have npm installed on your computer. For the name if you want a scoped package, e.g. @samrobbins/package, ensure that the package name follows that structure, otherwise, you can just go with package. Remember that these have to be unique, so check npm to ensure you're not overlapping. Also ensure that your main key is output.js, or if you want it to be something different, then substitute your different name when I use output.js further down in this file

The first thing we need is a JavaScript bundler, for this I've chosen rollup, but you could do this with any of them. To install rollup, run

npm i rollup

The config file for rollup is rollup.config.js, so create that file, and we'll start simple with this

export default {
  input: "./index.js",
  output: {
    file: "./output.js",
    format: "esm",
  },
}

This takes the file index.js and creates a file output.js, with the format of ES Modules (esm).

At the time of writing, the postcss plugin we'll use later is only compatible with postcss 7, so we'll install everything for the compatibility version of Tailwind CSS

npm install tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

and create a simple postcss.config.js

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

Then we can initialise Tailwind CSS

npx tailwindcss init

This will create a tailwind.config.js file, and we can add to purge whichever folder we're going to put our components in by adding a purge key like this

module.exports = {
  purge: ["./components/**/*.js"],
  //...
};

Create a styles folder with tailwind.css inside, with the following text

@tailwind base;
@tailwind components;
@tailwind utilities;

This allows you to use things like @layers in the future if you need to.

Now Tailwind is set up, we want to go back to rollup so it understands what to do with it

For this we want to use the rollup-plugin-postcss plugin, which can be installed like this

npm install rollup-plugin-postcss

You can then use this in your rollup.config.js file by adding this at the top

import postcss from "rollup-plugin-postcss";

Then going into the main object, add a key called plugins, which is a list of functions, and you can add postcss like this

plugins: [
    postcss({
      config: {
        path: "./postcss.config.js",
      },
      extensions: [".css"],
      minimize: true,
      inject: {
        insertAt: "top",
      },
    }),
  ],

Here we're giving it the path of our postcss path under config, telling it which files to run postcss on with extensions and minimizing the output with minimise. An important key here is inject, this determines where in the head of your page the CSS will be inserted. This is very important with Tailwind CSS as it has an order of priority, allowing for patterns like block md:flex and it will use display block less than the md viewport width, then flex after that. However, if there is a definition for block after the definition for md:flex, then this pattern will not work as expected. So in order for the CSS to work as you would expect, you want it at the top, and the inject key used as shown does this.

As these are React components, we expect React to be included in the application we're using these, so we want to add react and react-dom as peer dependencies. So add a peerDependencies key in your package.json and add the latest versions of those packages, at the time of writing, looking like this

"peerDependencies": {
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
},

You can then specify the same kind of thing in rollup.config.js by adding these under the external key like this

external: ["react", "react-dom"],

Next we want to generate the index.js file we referenced earlier. How specifically you export from your component files may change this, but for my example, I'm doing export default from all my component files. So for each component I have, I want to add a line that looks like this

export { default as Answer } from "./components/answer.js";

This will reexport the default export as Answer from this file.

If you run rollup -c (-c specifying that you have a custom config) you should see that it builds to an output.js file. However if you look in here, you will see that the CSS is huge as Tailwind doesn't know if you're running locally or in production, and so assumes local and includes all the styles. You can quickly get around this by running

NODE_ENV=production rollup -c

but any way to set the environment variable NODE_ENV to production will work

We also want to add babel to this project, which allows for using newer JavaScript features on older browsers.

To do this, we need to install a few packages to get all the features we need

npm install @babel/core @babel/preset-env @babel-preset-react @rollup/plugin-babel babel-loader

In our rollup.config.js we need to import the rollup plugin we just installed by adding this at the top

import babel from "@rollup/plugin-babel";

and then this new entry in our plugins array:

babel({
      babelHelpers: "bundled",
      exclude: "node_modules/**",
    }),

and finally to tell babel what we want it to do, create a .babelrc file in your root directory with the following code

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

NPM publishing

Now we want to publish this package to npm, so make sure you have an npm account, then login with npm login, and add the flag --scope with your username, so I do:

npm login --scope=@samrobbins

Then to publish from the command line you can do

npm publish --access public

and this will publish it to npm. You need the --access public flag if you have a free account as scoped packages default to restricted but restricted packages are paid on npm.

GitHub action

Now we have a published package, but it's a bit of a pain to have to do this manually every time, so you can go further by creating a GitHub action to do it automatically

You can do this by creating a file insider .github/workflows of the yml format, for example, I created publish.yml

We'll go through this step by step, but if you want the whole file I'll put it at the bottom

First we want a name for our workflow, so we can see from the UI what is running if we have multiple actions, so set

name: Node.js package

or whatever you want it called.

Next we want a trigger for this, I've chosen to have it when I create a GitHub release so that GitHub releases and NPM are in sync, but you can change the trigger if you want.

on:
  release:
    types: [created]

Then we want to determine what is actually running. We don't need any operating specific features, so ubuntu is the best choice for the operating system to run it on.

jobs:
  build:
    runs-on: ubuntu-latest

The rest of these steps sit underneath the build: key just like runs-on

First we want to get the code from our repository, this can be done with the actions/checkout action

- uses: actions/checkout@v2

Then we want to set up our Node.js environment. Using the latest version of Node.js is suggested as some packages will use more modern Node.js features, for example I had Tailwind fail on Node.js 10. And we want to use the official npm registry as that's the one everyone is used to, but if you want to use something like the GitHub package repository, you could change that here.

- uses: actions/setup-node@v1
    with:
        node-version: '12.x'
        registry-url: 'https://registry.npmjs.org'

Then we want to install all our packages, and run the build command

- run: npm install
- run: npm run-script build

And finally we want to publish. Instead of using npm login like we did locally, here we want to instead use a token. This can be found on the npm website, and make sure you get a publish token. Then add this as NPM_TOKEN in the repository you will be running the action in.

This will allow the final statement to work

- run: npm publish --access public
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

So in total, the file should look like this

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v1
      with:
        node-version: '12.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm install
    - run: npm run-script build
    - run: npm publish --access public
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

And that's it! Whenever you create a release, it'll be published