# 🖨  Gutenberg

**A markdown/MDX-based site generator.**

**Links**:

- [Source Code](https://github.com/abhayvatsa/gutenberg)
- See it live at: https://abhayvatsa.com



A modern printing press. Markdown is underpowered. Enter remark, rehype and MDX.

🖨  Gutenberg

# HTML

This is just a random snippet for demo purposes.

```html
<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
  </body>
</html>
```


HTML

# 📸 Vatsagram

A minimalistic, unbranded, performant web application for photos. Written in React, TypeScript and Next.js. Using Sharp for image processing. Deployed on Vercel.

**Links**:

- [Source Code](https://github.com/abhayvatsa/vatsagram)
- See it live at: https://vatsagram.com

**Optimizations**:

- [x] Blur Up technique: server rendered low res b64 images with gaussian blur
- [x] lazy loading, intersection observer
- [x] srcset with a range of sizes, appropriately compressed images
- [x] support webp, jpeg, (avif??)
- [ ] Do add'l optimizations [listed here](https://www.industrialempathy.com/posts/image-optimizations/)
- [ ] Modal for post page (when routed on client-side)


Photos first. A minimalistic photo experience on the web with a focus on performance.

📸 Vatsagram

# Making Markdown Usable!

## Table of Contents

## The Past

If you're like me, you've used markdown for a long time. You may have first seen it on GitHub or found it in the source code of one of your favorite libraries. I remember when I first used markdown, I instantly saw the value proposition. In my view, the three biggest pros for markdown are:

1. It has an open specification. No more sharing slow-opening, proprietary document formats like Microsoft Word or Adobe PDFs. Very portable docs.
2. It has a lightweight markup language that is human-readable. The syntax visually resembles the corresponding HTML and doesn't require a rich text editor to edit/review/display.
3. It's straightforward to learn and expressive. Writing `# My Title`  and `## My Title` is visually easy to spot and easy to `grep` for.

If you're also like me, you've tried different publishing solutions over the years. Here are some of the platforms I've used with the context of why I chose them. The pros and cons aren't comparative. Instead, they are the progression of requirements in chronological order.

| Tool                                                                                     | Context of use case                           | Pros                                                                          | Cons                                                        |
| ---------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------              | -------------------------------------------------------     |
| GitHub `README.md`                                                                       | My first markdown experience                  | Built into Github and free from PDFs and Word docs. Also, syntax highlighting | The UX while navigating interlinked markdown files is awful |
| [react-markdown](https://github.com/rexxars/react-markdown)                              | I wanted to build a markdown-powered blog     | All the flexibility/power you need. Easy to understand.                       | Everything was custom-written, self-hosted                  |
| [GitBook](https://github.com/GitbookIO/gitbook)                                          | Greenfield project at work                    | Nice UI/default theme, search. Can publish to PDF (had to once!)              | Requires hosting                                            |
| [GitHub Wiki](https://help.github.com/en/github/building-a-strong-community/about-wikis) | Greenfield project at work                    | No need to host by self.                                                      | Not the best UX, search is lacking                          |
| [GitHub Pages](https://pages.github.com/)                                                | Greenfield project at work                    | No need to self-host, Jekyll is built-in, themes are easy to use              | As a React developer, I don't like templating languages     |

Looking back, I could have done a better job of vetting potential alternatives before committing to an option. The way I've processed this journey is: each stage served the purpose of growing my skills as a developer. Each platform provided an opportunity to learn something. I learned how to buy a domain, how to write maintainable CSS, and even how to use Ansible to configure a server. At the end of the day, all of these docs were written in markdown and are portable. So, no vendor lock-in!

## The Present

Today, I am interested in having a bit more control of markdown documents. More precisely, I'm interested in using specific plugins that can enhance markdown by programmatically altering the abstract syntax tree. This is enabled through processors and plugins like [remark](https://github.com/remarkjs/remark), [MDX](https://github.com/mdx-js/mdx) and [rehype](https://github.com/rehypejs/rehype). These processors enable writing impressive webpages with plain-text documents.

**MDX**

Much like you can write *HTML* in a *markdown* document, you can write *JSX* within an *MDX* document. MDX is a nifty syntax extension for markdown that enables including React components within markdown. Imagine being able to include components like `<FunFact/>`, `<Chart/>`, `<Video/>` and `<PopQuestion/>` to increase interactivity of your plain-text documents. The components can encapsulate state, styling and interactivity in a simple API for authors. Let's look at what a `<PopQuestion />` might look like!

```jsx
<PopQuestion
  question="Who originally proposed MDX?"
  answer="Guillermo Rauch (@rauchg)"
/>
```

**Click below** and see the interactivity provided by the source code above. Simple isn't it?

<PopQuestion
  question="Who originally proposed MDX?"
  answer="Guillermo Rauch (@rauchg)"
/>

With these embedded React components you could even query external APIs. Imagine having interactive React components displaying _live_ data, all contained within an MDX document. Given a library of a few React components, an author could have the power to author fairly engaging documents with minimal code.

**Remark**

Remark provides a whole [suite of plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) worth checking out. I've used them to autogenerate a table of contents, add attributes to the headings (for anchor links), add syntax highlighting and much more.

## The Future

> "If you optimize everything, you will always be unhappy." - Donald Knuth

One of the first lessons in engineering and computer science is that you can't optimize for everything. Markdown is human-readable plain text, and consequently, it can easily be checked into your version control, aggressively peer-reviewed, grepped, diffed, statically compiled and displayed on responsive screen sizes. One of the limitations of this plain-text format happens when you want to include diagrams and quickly add attachments. For features like that, we often end up losing the original properties of plain text and end up with platforms like Confluence and Microsoft Word.

So, I'm interested in seeing what kinds of experiences are possible while staying true to the design decision to use plain text. Stay tuned to hear more!


Enhancing markdown is so much easier than I thought. Enter MDX, plugins and ASTs.

Making Markdown Usable!

# About me

## The Journey

So, let's date myself... As a 90s kid, I grew up with the web. And, in true 90s style, I made my first website with [GeoCities](https://en.wikipedia.org/wiki/Yahoo!_GeoCities) for my [Age of Empires II](https://en.wikipedia.org/wiki/Age_of_Empires_II) clan. It was amazingly terrible in all the ways you'd expect. But, I was so excited to share something I made with the world. Fast forward to today and I'm _still_ just as excited. I'm interested in web browsers, computer networks, JavaScript and good tooling - basically, anything related to developing, delivering, distributing rich web applications.

## Target Audience & Content

You'll find me writing about things that I've been learning. I like to write about new technologies and tools that I've been tinkering with. I tend to focus on the _gotchas_ or _insights_ over exhaustive tutorials. The reasoning is that step-by-step guides tend to "rot" over time as software evolves whereas good ideas don't.

## Reach out!

I love to hear from former colleagues, classmates and like-minded people. If you find something interesting, incorrect or have a comment [reach out on Twitter](https://twitter.com/abhayvatsa). I always appreciate feedback. Thanks for reading.


About me

# Rebooting my blog

## Why now?

It's a story as old as time. A software engineer decides to build a bespoke website on a branded domain to start a blog. They proceed to write a few posts and never look at it again. I know it well because that's how my previous personal blog went down. So, why spend _all that effort_ for a few posts? Why wouldn't people just use Medium? Well, writing the software is half the fun. It feels rewarding to have a creative outlet to control the presentation of your thoughts. Additionally, I'm tired of the paywalls, required logins, advertisements, excessive branding elements that get in the way of content on sites like Medium, Facebook, Twitter. They add up to a really poor user experience.

At work, I've recently moved teams and I'm doing much more frontend work. For the last few years I'd been avoiding frontend work in favor of working on backend services for cloud infrastructure. I quickly found myself excited about hacking around with web technologies and I wanted to build something from scratch (w.r.t. styling/design). I also wanted to experiment with [Next.js](https://nextjs.org/docs/getting-started), [MDX](https://github.com/mdx-js/mdx), [remark plugins](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins) and various CSS in JS libraries. I'm intrigued by some of the recent trends toward precompilation and [static exporting](https://nextjs.org/features/static-exporting) in addition to the flexibility of MDX to pull in React components. I think they can all add up to a really good user experience - for both the reader and the writer.

## Looking forward

I'm excited to share my thoughts here and will continue to make improvements on the software. Thanks for reading :).


Rebooting my blog with technologies de jour.

Hi there, I'm Abhay!

Projects

🖨 Gutenberg

📸 Vatsagram

Recent Articles

Making Markdown Usable!

Rebooting my blog