A developer blog starter for 2020.
Next.js
React
TypeScript
Markdown
syntax highlighting
SEO
RSS generation
if you're happy and you know it, star this repo
- Works as a Markdown-based static-site generator out of the box: just add new blog posts to
/md/blog - Supports exporting to fully static assets (powered by Next.js)
- Hot reload (powered by Next.js)
- Makes it easy to write custom pages/code in React + TypeScript
- Provides a
Markdown.tsxcomponent with support for GitHub-style syntax highlighting - Automatic RSS feed generation
- SEO best practices (title tag, meta tags, canonical URLs)
Read more about the motivation + design behind Devii at https://colinhacks.com/blog/devii.
This repo contains the code for https://devii.dev.
devii.dev serves as both the documentation AND a working demo of Devii. After you clone/fork it, you can look through the code to learn how Devii works. Then you can rip out everything you don't like, customize everything else, and build your own tools and components on top of the foundation Devii provides!
Your personal website is the online manifestation of you. Devii doesn't really provide much out of the box. It provides some nice Medium-style default styles for your blog posts and some tools for loading/rendering Markdown. But you'll have to implement your own homepage more or less from scratch. And that's the point! Don't settle for some theme. Build something that represents you.
To get started:
- Fork this repo
-
git clone git@github.com:yourusername/devii.git my-blog cd my-blog yarn - Start the development server with
yarn dev. This should start a server onhttp://localhost:3000.
The core of this repo is Next.js. We chose Next.js because it's the simplest, most elegant way to generate a static version of a React-based website. The documentation is excellent; read it first: Next.js Documentation.
Here's is an abbreviated version of the project structure. Certain config files (next.config.js, next-end.d.ts, .gitignore) have been removed for simplicity.
.
├── README.md
├── public // all static assets (images, css, etc) go here
├── pages // every .tsx component in this dir becomes a page of the final site
| ├── index.tsx // the home page (which has access to the list of all blog posts)
| ├── blog
| ├── [blog].md // a template component that renders the blog posts under `/md/blog`
├── md
| ├── blog
| ├── devii.md // this page!
├── whatever.md // every MD file in this directory becomes a blog post
├── components
| ├── BlogPost.tsx
| ├── Code.tsx
| ├── Footer.tsx
| ├── Header.tsx
| ├── Markdown.tsx
| ├── Meta.tsx
| ├── <various>
├── loader.ts // contains utility functions for loading/parsing Markdown
├── node_modules
├── tsconfig.json
├── package.json
Next.js generates a new webpage for each file in the pages directory. If you want to add an About page to your blog, just add about.tsx inside pages and start writing the page.
By default the repo only contains two pages: a home page (/pages/index.tsx) and a blog page (/pages/[blog].md).
The file [blog].ts follows the Next.js convention of using square brackets to indicate a dynamic route.
The home page is intentionally minimal. You can put whatever you want in index.tsx; one of our goals in designing Devii was to place no restrictions on the developer. Use your imagination! Your website is the online manifestion of you. You can use whatever npm packages or styling libraries you like.
Devii is unopinionated about styling. Because your Devii site is a standard React app under the hood, you can use your favorite library from npm to do styling.
Devii provides certain styles by default, notably in the Markdown renderer (/components/Markdown.tsx). Those styles are implemented using Next's built-in styling solution styled-jsx. Unfortunately it was necessary to make those styles global, since styled-jsx doesn't play nice with third-party components (in this case react-markdown).
Feel free to re-implemement the built-in styles with your library of choice If you choose to use a separate styling library (emotion is pretty glorious) then you could re-implement the default styles
Just add a Markdown file under md/blog/ to create a new blog post:
- Create a new Markdown file called
foo.mdwithin the/md/blogdirectory - Add in some basic Markdown content
- Then go to
http://localhost:3000/blog/foo. You should see the new post.
Every Markdown file can include a "frontmatter block" containing various metadata. Devii provides a loadPost utility that loads a Markdown file, parses it's frontmatter metadata, and returns a structured PostData object:
type PostData = {
path: string;
title?: string;
subtitle?: string;
description?: string; // used for SEO
canonicalUrl?: string; // used for SEO
datePublished?: number; // Unix timestamp
author?: string;
authorPhoto?: string;
authorHandle?: string; // twitter handle
tags?: string[];
bannerPhoto?: string;
thumbnailPhoto?: string;
};For example, here is the frontmatter blog from the sample blog post (md/blog/the-ultimate-tech-stack.md):
---
title: Introducing Devii
subtitle: Bringing the power of React, TypeScript, and static generation to dev blogs everywhere
datePublished: 1589064522569
author: Ben Bitdiddle
tags:
- Devii
- Blogs
authorPhoto: /img/profile.jpg
bannerPhoto: /img/brook.jpg
thumbnailPhoto: /img/brook.jpg
---
View /loader.ts to see how this works.
Just add your Google Analytics ID (e.g. 'UA-999999999-1') to globals.ts and Devii will automatically add the appropriate Google Analytics snippet to your site. Go to /pages/_app.ts to see how this works or customize this behavior.
The Markdown renderer (Markdown.tsx) provides a default style inspired by Medium. Just modify the CSS in Markdown.tsx to customize the design to your liking.
You can easily drop code blocks into your blog posts using triple-backtick syntax (just like GitHub). No more embedding CodePen iframes! 🚀
Works out-of-the-box for all programming languages. Specify your language with a "language tag". So this:
```ts
// pretty neat huh?
const test = (arg: string) => {
return arg.length > 5;
};
```
turns into
// pretty neat huh?
const test = (arg: string) => {
return arg.length > 5;
};View /components/Code.tsx to see how this works or customize this behavior.
You don't need to understand all of this to use Devii. Consider this an "advanced guide" you can use if you want to customize the structure of the site.
Markdown posts are loaded during Next.js static build step. Check out the Data Fetching documentation to learn more about this.
Here's the short version: if export a function called getStaticProps from one of your page components, Next.js will execute that function, take the result, and pass the props property (which should be another object) into your page as props.
You can dynamically load and parse a Markdown file using loadMarkdownFile, a utility function implemented in loader.ts. It is an async function that returns a PostData TypeScript object containing all the metadata keys listed above:
For an example of this, check out the getStaticProps implementation from the homepage. The function calls loadBlogPosts - a utilty function that loads every blog posts in the /md/blog/ directory, parses them, and returns PostData[].
export const getStaticProps = async () => {
const posts = await loadBlogPosts();
return { props: { posts } };
};There are a few utility functions in loader.ts that Devii uses. All functions are async! All functions accept a relative path which is expected to be _relative to the md/ directory. For instance loadPost('blog/test.md') would load /md/blog/test.md.
loadPostloads/parses a Markdown file and returns aPostDataloadBlogPosts: loads/parses all the files in/md/blog/. ReturnsPostData[]. Used inindex.tsxto load/render a list of all published blog postsloadMarkdownFile: loads a Markdown file but doesn't parse it. Returns the string content. Useful if you want to implement some parts of a page in Markdown and other parts in ReactloadMarkdownFiles: accepts a glob pattern and loads all the files inside/md/whose names match the pattern. Used internally byloadBlogPosts
You can generate a fully static version of your site using yarn build && yarn export. This step is entirely powered by Next.js. The static site is exported to the out directory.
After it's generated, use your static file hosting service of choice (Vercel, Netlify, Firebase Hosting, Amazon S3) to deploy your site.
There is a globals.ts file in the project root containing some settings/configuration metadata about your site:
yourName: Your name, used for the copyright tags in the footer and the RSS feed, e.g. Alyssa P. HackersiteName: The title of your blog, e.g.Alyssa's Cool Blog;siteDescription: A short description, used in themetadescription tag, e.g. 'I write about code 'n stuff';siteCreationDate: Used in the generated RSS feed. Use this format: 'March 3, 2020 04:00:00 GMT';twitterHandle: The twitter handle for you or your blog/company, used in the Twitter meta tags. Include the @ symbol, e.g. '@alyssaphacker';email: Your email, used as the "webMaster" and "managingEditor" field of the generated RSS feed, e.g.alyssa@example.com;url: The base URL of your website, used to "compute" default canonical links from relative paths, e.g. 'https://alyssaphacker.com';accentColor: The header and footer background color, e.g.#4fc2b4;
An RSS feed is auto-generated from your blog post feed. This feed is generated using the rss module (for converting JSON to RSS format) and showdown for converting the markdown files to RSS-compatible HTML.
For RSS generation to work, all your posts must contain a datePublished timestamp in their frontmatter metadata. To examine or customize the RSS generation, check out the rssUtil.ts file in the root directory.
Every blog post page automatically populated meta tags based on the post metadata. This includes a title tag, meta tags, og: tags, Twitter metadata, and a link tag containing the canonical URL.
The default value of the canonical URL is computed by concatenating the value of your url config (see Global Configs above) and the relative path of your post. Verify that the canonical URL is exactly equivalent to the URL in the browser when visiting your live site, otherwise your site's SEO may suffer.
There's nothing "under the hood" here. You can view and modify all the files that provide the functionality listed above. Devii just provides a project scaffold, some Markdown-loading loading utilities (in loader.ts), and some sensible styling defaults (especially in Markdown.tsx).
To get started customizing, check out the source code of index.tsx (the home page), BlogPost.tsx (the blog post template), and Markdown.tsx (the Markdown renderer).
Head to the GitHub repo to get started: https://github.com/colinhacks/devii. If you like this project, leave a ⭐️star⭐️ to help more people find Devii 😎
Starts the development server. Equivalent to next dev.
Creates an optimized build of your site. Equivalent to next build.
Exports your site to static files. All files are written to /out. Use your static file hosting service of choice (Firebase Hosting, Amazon S3, Vercel) to deploy your site. Equivalent to next export.