[WORK IN PROGRESS]
Many people have asked me how this website was built, and how they can build a similar one for themselves. Here, I will guide you through everything you need to create something similar.
Note to the reader: this guide is intentionally verbose and intended for those with minimal prior development experience. If you are familiar with web standards, all the relevant keywords used to make this website are listed at the top of the Stack section.
When I first began messing around with websites, I remember that even a very simple website was extremely intimidating — there are many unfamiliar terms that a lot of educational content skips over as too basic, and a frankly lot of moving parts you need to understand before you can make even a simple website. Web development is also unique from other fields of programming in that the modern standard changes quite rapidly; this post and many other similar guides may already be out of date. If you are just starting out with programming, my best advice is to read the documentation of all these technologies yourself in their entirety, as that will be the most up-to-date information on the web.
I also detail the motivations behind my choice of stack versus some other equally valid combination, an important aspect of programming I don’t see described online very often. Becoming a “real” programmer involves learning to choose between many perfectly good technologies and discerning which libraries and technologies are best suited to your particular use case, and the best way to gain this ability is from others and from testing different options out yourself.
Stack
This website is built using the following services and libraries: Svelte, SvelteKit, Tailwind, TypeScript, pnpm, and Vercel.
This may be all the information you need to get your own blog up and running. In fact, a good exercise is to try and put these pieces together yourself using the official docs available on the web. Beyond this point, I will assume almost no familiarity with these technologies and guide you through the process step-by-step.
pnpm
First, you’ll need a package manager. I use pnpm, which is an alternative to npm, the standard Javascript package manager. From a user perspective, pnpm has almost complete feature parity to npm, but I prefer pnpm because it’s usually faster and more space efficient. From their docs,
When using npm, if you have 100 projects using a dependency, you will have 100 copies of that dependency saved on disk. With pnpm, the dependency will be stored in a content-addressable store, so:
If you depend on different versions of the dependency, only the files that differ are added to the store. For instance, if it has 100 files, and a new version has a change in only one of those files, pnpm update will only add 1 new file to the store, instead of cloning the entire dependency just for the singular change.
All the files are saved in a single place on the disk. When packages are installed, their files are hard-linked from that single place, consuming no additional disk space. This allows you to share dependencies of the same version across projects.
Basically, it stores one version of a package and references it for all your projects that use pnpm, whereas npm installs a fresh package for every project, leading to duplicates. However, npm works just as well. You can also use yarn or some other package manager, but it may result in differences in the commands you need to run for setup and development.
Svelte
Now, we will set up a repo using Svelte. From Svelte’s website:
Svelte is a UI framework that uses a compiler to let you write breathtakingly concise components that do minimal work in the browser, using languages you already know — HTML, CSS and JavaScript.
The web uses a combination of HTML (for laying out content structure), CSS (for styling, colors, and fonts), and JavaScript (for interactivity) to display content and make it interactive. You can opt to write raw HTML or use a more complex framework like React, but I like Svelte for this blog because of its relative simplicity and ease of use. Svelte allows you to write code, styles, and content for a page / site all inside a single file, and under the hood, it compiles your code down to raw HTML, CSS, and Javascript. Other frameworks might ship a bunch of other functionality to the client browser that may be unnecessary for this simple use case; Svelte will only send that stuff when it’s actually necessary in the page we end up publishing.
To begin, we must navigate to the folder where you want to set up the website in a terminal. Then, following the Svelte setup guide, and replacing my-app with your name of choice, run:
npx sv create my-app
cd my-app
pnpm install
pnpm run dev
npx is just a command that comes bundled with package managers like npm (and pnpm) that allows you to run commands from libraries using your terminal. Above, we used Svelte’s scaffold command sv create to quickly set up the folder structure that is required to use Svelte for development. If you follow the localhost link printed in your console, you should see a basic Svelte website being served on your local development server. To stop running the development server, use Ctrl + C to exit the program.
SvelteKit
The above scaffold also sets the project up with SvelteKit, which is what is called a metaframework. Next.js is probably the most popular metaframework you’ll hear about, commonly used with React (as opposed to Svelte). Metaframeworks are basically libraries of code that handle really common tasks that are very much not worth rewriting every time you make a new website, like routing (painting new content when the user navigates to a new page on your site). It’s a great exercise to write your own router, but we won’t need that here.
The adoption of a metaframework is usually the point at which the file / folder names and structure of your project starts to matter, since metaframeworks have expectations for where to find the code for your site. See SvelteKit’s site for details on how they structure projects.
Now, we can start creating +page.svelte files inside of folders within the routes folder to make various pages on our site. You can also componentize by making files like SomeComponent.svelte and importing it from some other Svelte file.
Tailwind
Tailwind is a CSS framework that has gotten really popular. It basically allows you to put a bunch of keywords inside an HTML element’s class attribute to directly modify the styling of that element. It also provides very good base styles that keep you from choosing styles arbitrarily and help you stick to some standards. Some people think it’s terrible because it goes against the CSS principle that styles should be separate from layout, but if you really start using it, Tailwind becomes so second nature that normal CSS feels old and clunky in comparison.
In this site, I keep my main fonts in a top-level app.css file, while my post layout (see Tufte CSS) is governed by a tufte.css file. The rest of it is straight Tailwind, directly applied to each element.
TypeScript
TypeScript is a flavor of Javascript that has types where Javascript has none. Types are not strictly necessary but are very nice to have, since they help your compiler understand what kind of data you’re passing between functions and files. With a type checker, your compiler will stop you from trying to fit square pegs into circular holes, while plain Javascript lets you do pretty much whatever you want. TypeScript is pretty standard these days; it’s worth skimming the TypeScript handbook to learn all you need to know.
Vercel
Once you’re happy with your site, you need to put the code on a server where others can access it. Vercel is a company that will host your site for free and also makes it easy to purchase domain names (like cguti.xyz) and deploy your site there. To deploy your site with Vercel, make a Vercel account, link your Github, choose the repo containing the site, and follow the instructions they provide. Vercel owns SvelteKit and probably will automatically understand the frameworks you’re using, but you may need to use pnpm to install a Vercel adapter; this tells Vercel’s servers how to interpret your project structure and where to find the relevant code.
mdsvex
Addendums
Tufte CSS
The styling for my posts is a modified version of Tufte CSS, which you can read about and see examples of in this post. I like this styling setup because it allows me to add side notes and other fancy bells and whistles to my posts, all with plain CSS. This is a sidenote.
RSS
RSS is a very old technology that allows subscribers to get pinged when supportive websites to which they subscribe make changes to their site. Read about it here. Then, readers can view and manage subscriptions to sites using open source, free clients like NetNewsWire.
Metadata
Metadata is a part of the header of a page or site that tells browsers and search engines what your site is all about. This is basically the only Svelte componnet I use; in my lib folder, I have a Metadata.svelte file that I import in the layout file of each route to set things like the title and description. Metadata can get pretty important for SEO, if you’re into that.