starter-blog/README.md

220 lines
12 KiB
Markdown
Raw Normal View History

2021-01-11 16:57:24 +01:00
![tailwind-nextjs-banner](/public/static/images/twitter-card.png)
2021-01-09 10:50:00 +01:00
2021-01-11 16:57:24 +01:00
# Tailwind Nextjs Starter Blog
2021-05-23 06:55:28 +02:00
[![GitHub Repo stars](https://img.shields.io/github/stars/timlrx/tailwind-nextjs-starter-blog?style=social)](https://GitHub.com/timlrx/tailwind-nextjs-starter-blog/stargazers/)
[![GitHub forks](https://img.shields.io/github/forks/timlrx/tailwind-nextjs-starter-blog?style=social)](https://GitHub.com/timlrx/tailwind-nextjs-starter-blog/network/)
[![Twitter URL](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Ftwitter.com%2Ftimlrxx)](https://twitter.com/timlrxx)
2021-08-08 09:42:51 +02:00
[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&link=https://github.com/sponsors/timlrx)](https://github.com/sponsors/timlrx)
2021-05-23 06:47:28 +02:00
2021-01-11 17:16:01 +01:00
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/timlrx/tailwind-nextjs-starter-blog)
2021-12-20 21:02:50 +01:00
This is a [Next.js](https://nextjs.org/), [Tailwind CSS](https://tailwindcss.com/) blogging starter template. Probably the most feature-rich Next.js markdown blogging template out there. Comes out of the box configured with the latest technologies to make technical writing a breeze. Easily configurable and customizable. Perfect as a replacement to existing Jekyll and Hugo individual blogs.
2021-01-11 16:57:24 +01:00
2021-08-08 09:42:51 +02:00
Check out the documentation below to get started.
Facing issues? Check the [FAQ page](https://github.com/timlrx/tailwind-nextjs-starter-blog/wiki) and do a search on past issues. Feel free to open a new issue if none has been posted previously.
2021-12-20 21:02:50 +01:00
Feature request? Check the past discussions to see if it has been brought up previously. Otherwise, feel free to start a new discussion thread. All ideas are welcomed!
2021-06-09 18:02:59 +02:00
2021-04-24 09:51:31 +02:00
## Examples
2021-01-17 16:50:15 +01:00
2021-04-24 09:51:31 +02:00
- [Demo Blog](https://tailwind-nextjs-starter-blog.vercel.app/) - this repo
- [My personal blog](https://www.timlrx.com) - modified to auto-generate blog posts with dates
2021-08-08 09:42:51 +02:00
- [Aloisdg's cookbook](https://tambouille.vercel.app/) - with pictures and recipes!
2021-08-09 17:52:05 +02:00
- [GautierArcin's demo with next translate](https://tailwind-nextjs-starter-blog-seven.vercel.app/) - includes translation of mdx posts, [source code](https://github.com/GautierArcin/tailwind-nextjs-starter-blog/tree/demo/next-translate)
2021-08-28 19:54:02 +02:00
- [David Levai's digital garden](https://davidlevai.com/) - customized design and added email subscriptions
- [Thinh's Corner](https://thinhcorner.com/) - [customized layout](https://github.com/Th1nhNg0/th1nhng0.vercel.app/blob/5e73a420828d82f01e7147512a2c3273c4ec19f8/layouts/PostLayout.js) with sticky side table of contents
2021-09-08 18:46:06 +02:00
- [Leo's Blog](https://leohuynh.dev) - Tuan Anh Huynh's personal site. Add Snippets Page, Author Profile Card, Image Lightbox, ...
- [thvu.dev](https://thvu.dev) - Added `mdx-embed`, view count, reading minutes and more.
2021-12-24 05:24:12 +01:00
- [fiqrychoerudin.dev](https://www.fiqrychoerudin.dev/) - simple portfolio.
2021-12-26 10:39:41 +01:00
- [irvin.dev](https://www.irvin.dev/) - Irvin Lin's personal site. Added YouTube embedding.
- [the all JavaScript Blog](https://the-all-javascript-blog.vercel.app/) - a JavaScript enlightenment blog uses this
2022-01-19 21:48:39 +01:00
- [KirillSo.com](https://www.kirillso.com/) - Personal blog & website.
2022-02-01 15:38:22 +01:00
- [DevBoy Blog](https://devboy.vercel.app/) - M.Reza's personal blog
- [slightlysharpe.com](https://slightlysharpe.com) - [Tincre's](https://tincre.com) main company blog
- [blog.b00st.com](https://blog.b00st.com) - [b00st.com's](https://b00st.com) main music promotion blog
2022-01-30 11:33:49 +01:00
- [astrosaurus.me](https://astrosaurus.me/) - Ephraim Atta-Duncan's Personal Blog
2022-02-01 15:38:22 +01:00
- [dhanrajsp.me](https://dhanrajsp.me/) - Dhanraj's personal site and blog.
2022-01-30 21:36:00 +01:00
- [blog.r00ks.io](https://blog.r00ks.io/) - Austin Rooks's personal blog ([source code](https://github.com/Austionian/blog.r00ks)).
2022-02-01 16:39:57 +01:00
- [honghong.me](https://honghong.me) - Tszhong's personal website ([source code](https://github.com/tszhong0411/home))
- [alfoncode.com](https://alfoncode.com) - Alfonso García's personar website. Customized design ([source code](https://github.com/alfoncode/personal-web))
2021-04-24 09:51:31 +02:00
2021-08-08 09:42:51 +02:00
Using the template? Feel free to create a PR and add your blog to this list.
2021-01-11 17:16:01 +01:00
2021-01-11 16:57:24 +01:00
## Motivation
2021-08-08 09:42:51 +02:00
I wanted to port my existing blog to Nextjs and Tailwind CSS but there was no easy out of the box template to use so I decided to create one. Design is adapted from [Tailwindlabs blog](https://github.com/tailwindlabs/blog.tailwindcss.com).
2021-01-11 16:57:24 +01:00
I wanted it to be nearly as feature-rich as popular blogging templates like [beautiful-jekyll](https://github.com/daattali/beautiful-jekyll) and [Hugo Academic](https://github.com/wowchemy/wowchemy-hugo-modules) but with the best of React's ecosystem and current web development's best practices.
## Features
2021-12-15 11:05:37 +01:00
- Easy styling customization with [Tailwind 3.0](https://tailwindcss.com/blog/tailwindcss-v3) and primary color attribute
2021-01-11 16:57:24 +01:00
- Near perfect lighthouse score - [Lighthouse report](https://www.webpagetest.org/result/210111_DiC1_08f3670c3430bf4a9b76fc3b927716c5/)
- Lightweight, 45kB first load JS, uses Preact in production build
2021-01-11 16:57:24 +01:00
- Mobile-friendly view
- Light and dark theme
2022-02-01 15:38:22 +01:00
- Self-hosted font with [Fontsource](https://fontsource.org/)
2021-07-28 17:36:42 +02:00
- Supports [plausible](https://plausible.io/), [simple analytics](https://simpleanalytics.com/) and google analytics
2021-01-11 16:57:24 +01:00
- [MDX - write JSX in markdown documents!](https://mdxjs.com/)
2021-07-11 17:35:19 +02:00
- Server-side syntax highlighting with line numbers and line highlighting via [rehype-prism-plus](https://github.com/timlrx/rehype-prism-plus)
2021-01-11 16:57:24 +01:00
- Math display supported via [KaTeX](https://katex.org/)
2021-12-20 21:02:50 +01:00
- Citation and bibliography support via [rehype-citation](https://github.com/timlrx/rehype-citation)
2021-01-11 16:57:24 +01:00
- Automatic image optimization via [next/image](https://nextjs.org/docs/basic-features/image-optimization)
2021-07-11 17:35:19 +02:00
- Flexible data retrieval with [mdx-bundler](https://github.com/kentcdodds/mdx-bundler)
2021-01-11 16:57:24 +01:00
- Support for tags - each unique tag will be its own page
2021-06-09 18:02:59 +02:00
- Support for multiple authors
- Blog templates
- TOC component
- Support for nested routing of blog posts
- Newsletter component with support for mailchimp, buttondown, convertkit and klaviyo
2021-07-18 10:02:35 +02:00
- Supports [giscus](https://github.com/laymonage/giscus), [utterances](https://github.com/utterance/utterances) or disqus
2021-02-14 12:16:14 +01:00
- Projects page
2021-12-22 02:12:44 +01:00
- Preconfigured security headers
2021-01-11 16:57:24 +01:00
- SEO friendly with RSS feed, sitemaps and more!
2021-01-12 15:47:03 +01:00
## Sample posts
- [A markdown guide](https://tailwind-nextjs-starter-blog.vercel.app/blog/github-markdown-guide)
- [Learn more about images in Next.js](https://tailwind-nextjs-starter-blog.vercel.app/blog/guide-to-using-images-in-nextjs)
- [A tour of math typesetting](https://tailwind-nextjs-starter-blog.vercel.app/blog/deriving-ols-estimator)
- [Simple MDX image grid](https://tailwind-nextjs-starter-blog.vercel.app/blog/pictures-of-canada)
- [Example of long prose](https://tailwind-nextjs-starter-blog.vercel.app/blog/the-time-machine)
- [Example of Nested Route Post](https://tailwind-nextjs-starter-blog.vercel.app/blog/nested-route/introducing-multi-part-posts-with-nested-routing)
2021-01-12 15:47:03 +01:00
2021-01-11 16:57:24 +01:00
## Quick Start Guide
2021-12-08 05:41:57 +01:00
1. JS (official support)
2021-12-15 11:05:37 +01:00
2021-12-08 05:41:57 +01:00
```bash
npx degit https://github.com/timlrx/tailwind-nextjs-starter-blog.git
```
2021-12-15 11:05:37 +01:00
or with TypeScript (community support)
2021-12-15 11:05:37 +01:00
2021-12-08 05:41:57 +01:00
```bash
npx degit timlrx/tailwind-nextjs-starter-blog#typescript
```
2. Personalize `siteMetadata.js` (site related information)
2021-06-09 18:02:59 +02:00
3. Personalize `authors/default.md` (main author)
4. Modify `projectsData.js`
5. Modify `headerNavLinks.js` to customize navigation links
6. Add blog posts
7. Deploy on Vercel
2021-01-11 16:57:24 +01:00
2021-12-24 10:44:39 +01:00
## Installation
```bash
npm install
```
2021-01-11 16:57:24 +01:00
## Development
2021-01-09 10:50:00 +01:00
First, run the development server:
```bash
2021-01-11 16:57:24 +01:00
npm start
2021-12-08 05:41:57 +01:00
```
2021-12-15 11:05:37 +01:00
or
2021-12-15 11:05:37 +01:00
2021-12-08 05:41:57 +01:00
```bash
2021-01-11 16:57:24 +01:00
npm run dev
2021-01-09 10:50:00 +01:00
```
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
2021-01-11 16:57:24 +01:00
## Extend / Customize
`data/siteMetadata.js` - contains most of the site related information which should be modified for a user's need.
2021-01-11 16:57:24 +01:00
2021-06-09 18:02:59 +02:00
`data/authors/default.md` - default author information (required). Additional authors can be added as files in `data/authors`.
2021-12-20 21:02:50 +01:00
`data/projectsData.js` - data used to generate styled card on the projects page.
2021-02-14 12:16:14 +01:00
`data/headerNavLinks.js` - navigation links.
2021-01-11 16:57:24 +01:00
`data/logo.svg` - replace with your own logo.
`data/blog` - replace with your own blog posts.
`public/static` - store assets such as images and favicons.
2021-06-19 12:34:44 +02:00
`tailwind.config.js` and `css/tailwind.css` - contain the tailwind stylesheet which can be modified to change the overall look and feel of the site.
2021-01-11 16:57:24 +01:00
`css/prism.css` - controls the styles associated with the code blocks. Feel free to customize it and use your preferred prismjs theme e.g. [prism themes](https://github.com/PrismJS/prism-themes).
2021-12-20 21:02:50 +01:00
`components/social-icons` - to add other icons, simply copy an svg file from [Simple Icons](https://simpleicons.org/) and map them in `index.js`. Other icons use [heroicons](https://heroicons.com/).
2021-01-11 16:57:24 +01:00
`components/MDXComponents.js` - pass your own JSX code or React component by specifying it over here. You can then call them directly in the `.mdx` or `.md` file. By default, a custom link and image component is passed.
2021-01-09 10:50:00 +01:00
2021-01-11 16:57:24 +01:00
`layouts` - main templates used in pages.
2021-01-09 10:50:00 +01:00
2021-12-22 02:12:44 +01:00
`pages` - pages to route to. Read the [Next.js documentation](https://nextjs.org/docs) for more information.
`next.config.js` - configuration related to Next.js. You need to adapt the Content Security Policy if you want to load scripts, images etc. from other domains.
2021-01-09 10:50:00 +01:00
## Post
### Frontmatter
Frontmatter follows [Hugo's standards](https://gohugo.io/content-management/front-matter/).
Currently 7 fields are supported.
```
title (required)
date (required)
tags (required, can be empty array)
lastmod (optional)
draft (optional)
summary (optional)
2021-01-18 16:41:48 +01:00
images (optional, if none provided defaults to socialBanner in siteMetadata config)
2021-06-09 18:02:59 +02:00
authors (optional list which should correspond to the file names in `data/authors`. Uses `default` if none is specified)
layout (optional list which should correspond to the file names in `data/layouts`)
```
Here's an example of a post's frontmatter:
```
---
title: 'Introducing Tailwind Nexjs Starter Blog'
date: '2021-01-12'
lastmod: '2021-01-18'
tags: ['next-js', 'tailwind', 'guide']
draft: false
summary: 'Looking for a performant, out of the box template, with all the best in web technology to support your blogging needs? Checkout the Tailwind Nextjs Starter Blog template.'
images: ['/static/images/canada/mountains.jpg', '/static/images/canada/toronto.jpg']
2021-06-09 18:02:59 +02:00
authors: ['default', 'sparrowhawk']
layout: PostLayout
---
```
### Compose
2021-01-18 14:49:59 +01:00
2021-07-04 10:12:36 +02:00
Run `node ./scripts/compose.js` to bootstrap a new post.
2021-01-18 14:49:59 +01:00
2021-07-04 10:12:36 +02:00
Follow the interactive prompt to generate a post with pre-filled front matter.
2021-01-18 14:49:59 +01:00
2021-01-11 16:57:24 +01:00
## Deploy
2021-01-09 10:50:00 +01:00
2021-01-11 16:57:24 +01:00
**Vercel**
The easiest way to deploy the template is to use the [Vercel Platform](https://vercel.com) from the creators of Next.js. Check out the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
2021-01-09 10:50:00 +01:00
2021-12-20 21:02:50 +01:00
**Netlify / GitHub Pages / Firebase etc.**
As the template uses `next/image` for image optimization, additional configurations have to be made to deploy on other popular static hosting websites like [Netlify](https://www.netlify.com/) or [GitHub Pages](https://pages.github.com/). An alternative image optimization provider such as Imgix, Cloudinary or Akamai has to be used. Alternatively, replace the `next/image` component with a standard `<img>` tag. See [`next/image` documentation](https://nextjs.org/docs/basic-features/image-optimization) for more details.
2021-08-08 09:42:51 +02:00
2021-09-10 17:24:41 +02:00
The API routes used in the newsletter component cannot be used in a static site export. You will need to use a form API endpoint provider and substitute the route in the newsletter component accordingly. Other hosting platforms such as Netlify also offer alternative solutions - please refer to their docs for more information.
2021-08-08 09:42:51 +02:00
## Support
2021-12-20 21:02:50 +01:00
Using the template? Support this effort by giving a star on GitHub, sharing your own blog and giving a shoutout on Twitter or becoming a project [sponsor](https://github.com/sponsors/timlrx).
2021-08-08 09:42:51 +02:00
## Licence
[MIT](https://github.com/timlrx/tailwind-nextjs-starter-blog/blob/master/LICENSE) © [Timothy Lin](https://www.timrlx.com)