Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tidbitsjs/3dbits


https://github.com/tidbitsjs/3dbits

Last synced: 2 days ago
JSON representation

Awesome Lists containing this project

README 

        
![tailwind-nextjs-banner](/public/static/images/twitter-card.png)



# Tailwind Nextjs Starter Blog



[![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)

[![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)



[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/timlrx/tailwind-nextjs-starter-blog)



This is a [Next.js](https://nextjs.org/), [Tailwind CSS](https://tailwindcss.com/) blogging starter template. Version 2 is based on Next App directory with [React Server Component](https://nextjs.org/docs/getting-started/react-essentials#server-components) and uses [Contentlayer](https://www.contentlayer.dev/) to manage markdown content.



Probably the most feature-rich Next.js markdown blogging template out there. Easily configurable and customizable. Perfect as a replacement to existing Jekyll and Hugo individual blogs.



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.



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!



Looking for an Astro alternative? Check out the unofficial [Tailwind Astro Template](https://github.com/wanoo21/tailwind-astro-starting-blog).



Looking for a Remix-run alternative? Check out the unofficial [Tailwind Remix-run Starter Blog Template](https://github.com/SangeetAgarwal/tailwind-remix-run-mdxjs-typescript-starter-blog).



## Examples V2



- [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

- [ben.codes blog](https://ben.codes) - Benoit's personal blog about software development ([source code](https://github.com/bendotcodes/bendotcodes))

- [tsix blog](https://tsix.top) - A front-end engineer is used to record some knowledge points in work and study _中文_

- [SOTO's Blog](https://www.atksoto.com/) - A more personalized personal website upgraded from V1 ([source code](https://github.com/acsoto/soto-blog-nextjs))

- [Prabhu's Blog](https://prabhukirankonda.vercel.app) - Prabhu's Personal website with blog ([source code](https://github.com/prabhukiran8790/prabhukirankonda))

- [Rabby Hasan's Blog](https://blog.rabbyhasan.com.bd/) - Rabby Hasan's personal blog about full stack development with cloud ([source code](https://github.com/rabbyalone/myblog))

- [enscribe.dev](https://enscribe.dev) - enscribe's personal blog; cybersecurity shenanigans, frontend webdev, etc. ([source code](https://github.com/jktrn/enscribe.dev))



Using the template? Feel free to create a PR and add your blog to this list.



## Examples V1



[v1-blogs-showcase.webm](https://github.com/timlrx/tailwind-nextjs-starter-blog/assets/28362229/2124c81f-b99d-4431-839c-347e01a2616c)



Thanks to the community of users and contributors to the template! We are no longer accepting new blog listings over here. If you have updated from version 1 to version 2, feel free to remove your blog from this list and add it to the one above.



- [Aloisdg's cookbook](https://tambouille.vercel.app/) - with pictures and recipes!

- [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)

- [David Levai's digital garden](https://davidlevai.com/) - customized design and added email subscriptions

- [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.

- [irvin.dev](https://www.irvin.dev/) - Irvin Lin's personal site. Added YouTube embedding.

- [KirillSo.com](https://www.kirillso.com/) - Personal blog & website.

- [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

- [astrosaurus.me](https://astrosaurus.me/) - Ephraim Atta-Duncan's Personal Blog

- [dhanrajsp.me](https://dhanrajsp.me/) - Dhanraj's personal site and blog.

- [blog.r00ks.io](https://blog.r00ks.io/) - Austin Rooks's personal blog ([source code](https://github.com/Austionian/blog.r00ks)).

- [honghong.me](https://honghong.me) - Tszhong's personal website ([source code](https://github.com/tszhong0411/home))

- [marceloformentao.dev](https://marceloformentao.dev) - Marcelo Formentão personal website ([source code](https://github.com/marceloavf/marceloformentao.dev)).

- [abiraja.com](https://www.abiraja.com/) - with a [runnable JS code snippet component!](https://www.abiraja.com/blog/querying-solana-blockchain)

- [bpiggin.com](https://www.bpiggin.com) - Ben Piggin's personal blog

- [maqib.cn](https://maqib.cn) - A blog of Chinese front-end developers 狂奔小马的博客 ([源码](https://github.com/maqi1520/nextjs-tailwind-blog))

- [ambilena.com](https://ambilena.com/) - Electronic Music Blog & imprint for upcoming musicians.

- [dalelarroder.com](https://dalelarroder.com) - Dale Larroder's personal website and blog ([source code](https://github.com/dlarroder/dalelarroder))

- [0xchai.io](https://0xchai.io) - Chai's personal blog

- [techipedia](https://techipedia.vercel.app) - Simple blogging progressive web app with custom installation button and top progress bar

- [reubence.com](https://reubence.com) - Reuben Rapose's Digital Garden

- [axolo.co/blog](https://axolo.co/blog) - Engineering management news & axolo.co updates (with image preview for article in the home page)

- [musing.vercel.app](https://musing.vercel.app/) - Parth Desai's personal blog ([source code](https://github.com/pycoder2000/blog))

- [onyourmental.com](https://www.onyourmental.com/) - [Curtis Warcup's](https://github.com/Cwarcup) website for the On Your Mental Podcast ([source code](https://github.com/Cwarcup/on-your-mental))

- [cwarcup.com](https://www.cwarcup.com/) - Curtis Warcup's personal website and blog ([source code](https://github.com/Cwarcup/personal-blog)).

- [ondiek-elijah.me](https://www.ondiek-elijah.me/) - Ondiek Elijah's website and blog ([source code](https://github.com/Dev-Elie/ondiek-elijah)).

- [jmalvarez.dev](https://www.jmalvarez.dev/) - José Miguel Álvarez's personal blog ([source code](https://github.com/josemiguel-alvarez/nextjs-blog))

- [justingosses.com](https://justingosses.com/) - Justin Gosses's personal website and blog ([source code](https://github.com/JustinGOSSES/justingosses-website))

- [https://bitoflearning-9a57.fly.dev/](https://bitoflearning-9a57.fly.dev/) - Sangeet Agarwal's personal blog, replatformed to [remix](https://remix.run/remix) using the [indie stack](https://github.com/remix-run/indie-stack) ([source code](https://github.com/SangeetAgarwal/bitoflearning))

- [raphaelchelly.com](https://www.raphaelchelly.com/) - Raphaël Chelly's personal website and blog ([source code](https://github.com/raphaelchelly/raph_www))

- [kaveh.page](https://kaveh.page) - Kaveh Tehrani's personal blog. Added tags directory, profile card, time-to-read on posts directory, etc.



## Motivation



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).



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



- Next.js with Typescript

- [Contentlayer](https://www.contentlayer.dev/) to manage content logic

- Easy styling customization with [Tailwind 3.0](https://tailwindcss.com/blog/tailwindcss-v3) and primary color attribute

- [MDX - write JSX in markdown documents!](https://mdxjs.com/)

- Near perfect lighthouse score - [Lighthouse report](https://www.webpagetest.org/result/230805_BiDcBQ_4H7)

- Lightweight, 85kB first load JS

- Mobile-friendly view

- Light and dark theme

- Font optimization with [next/font](https://nextjs.org/docs/app/api-reference/components/font)

- Integration with [pliny](https://github.com/timlrx/pliny) that provides:

  - Multiple analytics options including [Umami](https://umami.is/), [Plausible](https://plausible.io/), [Simple Analytics](https://simpleanalytics.com/), Posthog and Google Analytics

  - Comments via [Giscus](https://github.com/laymonage/giscus), [Utterances](https://github.com/utterance/utterances) or Disqus

  - Newsletter API and component with support for Mailchimp, Buttondown, Convertkit, Klaviyo, Revue, and Emailoctopus

  - Command palette search with [Kbar](https://github.com/timc1/kbar) or Algolia

- Server-side syntax highlighting with line numbers and line highlighting via [rehype-prism-plus](https://github.com/timlrx/rehype-prism-plus)

- Math display supported via [KaTeX](https://katex.org/)

- Citation and bibliography support via [rehype-citation](https://github.com/timlrx/rehype-citation)

- Automatic image optimization via [next/image](https://nextjs.org/docs/basic-features/image-optimization)

- Support for tags - each unique tag will be its own page

- Support for multiple authors

- 3 different blog layouts

- 2 different blog listing layouts

- Support for nested routing of blog posts

- Projects page

- Preconfigured security headers

- SEO friendly with RSS feed, sitemaps and more!



## 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)



## Quick Start Guide



1. Clone the repo



```bash

npx degit 'timlrx/tailwind-nextjs-starter-blog'

```



2. Personalize `siteMetadata.js` (site related information)

3. Modify the content security policy in `next.config.js` if you want to use

   other analytics provider or a commenting solution other than giscus.

4. Personalize `authors/default.md` (main author)

5. Modify `projectsData.js`

6. Modify `headerNavLinks.js` to customize navigation links

7. Add blog posts

8. Deploy on Vercel



## Installation



```bash

yarn

```



## Development



First, run the development server:



```bash

yarn dev

```



Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.



Edit the layout in `app` or content in `data`. With live reloading, the pages auto-updates as you edit them.



## Extend / Customize



`data/siteMetadata.js` - contains most of the site related information which should be modified for a user's need.



`data/authors/default.md` - default author information (required). Additional authors can be added as files in `data/authors`.



`data/projectsData.js` - data used to generate styled card on the projects page.



`data/headerNavLinks.js` - navigation links.



`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.



`tailwind.config.js` and `css/tailwind.css` - tailwind configuration and stylesheet which can be modified to change the overall look and feel of the site.



`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).



`contentlayer.config.ts` - configuration for Contentlayer, including definition of content sources and MDX plugins used. See [Contentlayer documentation](https://www.contentlayer.dev/docs/getting-started) for more information.



`components/MDXComponents.js` - pass your own JSX code or React component by specifying it over here. You can then use them directly in the `.mdx` or `.md` file. By default, a custom link, `next/image` component, table of contents component and Newsletter form are passed down. Note that the components should be default exported to avoid [existing issues with Next.js](https://github.com/vercel/next.js/issues/51593).



`layouts` - main templates used in pages:



- There are currently 3 post layouts available: `PostLayout`, `PostSimple` and `PostBanner`. `PostLayout` is the default 2 column layout with meta and author information. `PostSimple` is a simplified version of `PostLayout`, while `PostBanner` features a banner image.

- There are 2 blog listing layouts: `ListLayout`, the layout used in version 1 of the template with a search bar and `ListLayoutWithTags`, currently used in version 2, which omits the search bar but includes a sidebar with information on the tags.



`app` - pages to route to. Read the [Next.js documentation](https://nextjs.org/docs/app) 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.



## Post



Content is modelled using [Contentlayer](https://www.contentlayer.dev/), which allows you to define your own content schema and use it to generate typed content objects. See [Contentlayer documentation](https://www.contentlayer.dev/docs/getting-started) for more information.



### Frontmatter



Frontmatter follows [Hugo's standards](https://gohugo.io/content-management/front-matter/).



Please refer to `contentlayer.config.ts` for an up to date list of supported fields. The following fields are supported:



```

title (required)

date (required)

tags (optional)

lastmod (optional)

draft (optional)

summary (optional)

images (optional)

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`)

canonicalUrl (optional, canonical url for the post for SEO)

```



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']

authors: ['default', 'sparrowhawk']

layout: PostLayout

canonicalUrl: https://tailwind-nextjs-starter-blog.vercel.app/blog/introducing-tailwind-nextjs-starter-blog

---

```



## Deploy



**Vercel**  

The easiest way to deploy the template is to deploy on [Vercel](https://vercel.com). Check out the [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.



**Netlify**

[Netlify](https://www.netlify.com/)’s Next.js runtime configures enables key Next.js functionality on your website without the need for additional configurations. Netlify generates serverless functions that will handle Next.js functionalities such as server-side rendered (SSR) pages, incremental static regeneration (ISR), `next/images`, etc.



See [Next.js on Netlify](https://docs.netlify.com/integrations/frameworks/next-js/overview/#next-js-runtime) for suggested configuration values and more details.



**Static hosting services / GitHub Pages / S3 / Firebase etc.**



1. Add `output: 'export'` in `next.config.js`. See [static exports documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#configuration) for more information.

2. Comment out `headers()` from `next.config.js`.

3. Change `components/Image.tsx` to use a standard `` tag instead of `next/image`:



   ```ts

   /* eslint-disable jsx-a11y/alt-text */

   /* eslint-disable @next/next/no-img-element */

   import NextImage, { ImageProps } from 'next/image'



   // @ts-ignore

   const Image = ({ ...rest }: ImageProps) => 



   export default Image

   ```



   Alternatively, to continue using `next/image`, you can use an alternative image optimization provider such as Imgix, Cloudinary or Akamai. See [image optimization documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization) for more details.



4. Remove `api` folder and components which call the server-side function such as the Newsletter component. Not technically required and the site will build successfully, but the APIs cannot be used as they are server-side functions.

5. Run `yarn build`. The generated static content is in the `out` folder.

6. Deploy the `out` folder to your hosting service of choice or run `npx serve out` to view the website locally.



## Frequently Asked Questions



### How can I add a custom MDX component?



Here's an example on how to create a donut chart from Chart.js (assuming you already have the dependencies installed) and use it in MDX posts. First, create a new `DonutChart.tsx` component in `components`:



```tsx

'use client'



import { Doughnut } from 'react-chartjs-2'

import { Chart as ChartJS, ArcElement, Tooltip, Legend } from 'chart.js'



ChartJS.register(ArcElement, Tooltip, Legend)



const DonutChart = ({ data }) => {

  return 

}



export default Doughnut

```



Since the underlying `Doughnut` component uses React hooks, we add the `'use client'` directive to specify that it is a client side component. Also, there is an existing issue which prevents named components from being used, so we need to export the component as the default export.



Next, add the component to `MDXComponents.tsx`:



```diff

...

+ import DonutChart from './DonutChart'



export const components: MDXComponents = {

  Image,

  TOCInline,

  a: CustomLink,

  pre: Pre,

+  DonutChart,

  BlogNewsletterForm,

}

```



You can now use the component in `.mdx` files:



```mdx

## Example Donut Chart



export const data = {

  labels: ['Red', 'Blue', 'Yellow'],

  datasets: [

    {

      label: '# of Votes',

      data: [12, 19, 3],

      backgroundColor: [

        'rgba(255, 99, 132, 0.2)',

        'rgba(54, 162, 235, 0.2)',

        'rgba(255, 206, 86, 0.2)',

      ],

      borderColor: ['rgba(255, 99, 132, 1)', 'rgba(54, 162, 235, 1)', 'rgba(255, 206, 86, 1)'],

      borderWidth: 1,

    },

  ],

}



```



### How can I customize the `kbar` search?



Add a `SearchProvider` component such as the one shown below and use it in place of the default `SearchProvider` component in `app/layout.tsx`.



`defaultActions` are the initial list of actions.



`onSearchDocumentsLoad` is a callback function that is called when the documents specified by `searchDocumentsPath` are loaded. Set `searchDocumentsPath` to `false` to disable the dynamically loaded search feature.



```tsx

'use client'



import { KBarSearchProvider } from 'pliny/search/KBar'

import { useRouter } from 'next/navigation'

import { CoreContent } from 'pliny/utils/contentlayer'

import { Blog } from 'contentlayer/generated'



export const SearchProvider = ({ children }) => {

  const router = useRouter()

  return (

     router.push('/'),

          },

          {

            id: 'projects',

            name: 'Projects',

            keywords: '',

            shortcut: ['p'],

            section: 'Home',

            perform: () => router.push('/projects'),

          },

        ],

        onSearchDocumentsLoad(json) {

          return json.map((post: CoreContent) => ({

            id: post.path,

            name: post.title,

            keywords: post?.summary || '',

            section: 'Blog',

            subtitle: post.tags.join(', '),

            perform: () => router.push(post.path),

          }))

        },

      }}

    >

      {children}

    

  )

}

```



## Support



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).



## Licence



[MIT](https://github.com/timlrx/tailwind-nextjs-starter-blog/blob/main/LICENSE) © [Timothy Lin](https://www.timlrx.com)