Analog User Guide - Get Started

Analog is a blog template based on Next.js, React, Tailwind CSS, and Content Collections. It is designed to be simple, fast, and customizable. This guide will introduce the basic information about Analog and help you get started with it.

Getting Started

There has been a brief Quick Start in README. This section will provide more detailed information about how to get started with Analog.

Deploy it on the Internet

Analog is based on Next.js, a modern web application generator. It can be deployed on various platforms, such as Vercel (Recommended) and GitHub Pages.

Deploy with Vercel

Vercel is a popular platform supporting site deployment.

1. Click the "Deploy with Vercel" button in README (You need to sign up for a Vercel account first).

   

2. Follow the instructions to deploy your blog. It will automatically fork the repository to your GitHub account.

   

3. Wait for the deployment to complete, and then you can access your blog at the URL provided by Vercel.

   

From now on, whenever you modify your website and push it to the repository, Vercel will automatically pull the update and build the deployment.

Deploy with GitHub Pages

GitHub Pages is a free hosting service provided by GitHub. Analog has built-in some workflows for GitHub Pages deployment.

1. Click the "Use this template" button in the repository to create your own repository.

   

2. Set the GitHub Pages source Settings -> Pages -> Build and Deployment Source to Actions.

   

3. Enable the workflow in the Actions tab.

   

4. You can find your blog at https://<username>.github.io/<repository>.

After the workflow is enabled, it will automatically deploy your blog to GitHub Pages whenever you push changes to the repository.

Deploy it Locally

If you want to preview your blog locally, you can follow these steps to temporarily deploy it on your computer.

Install Dependencies

You need to install Node.js and Yarn v2 to run Analog.

On macOS:

brew install node # install node.js >= 20
corepack enable # enable corepack for yarn 2

If you are using Linux or Windows, you can download prebuilt binaries from the official Node.js website.

Fork and Clone it to Your Computer

After you deploy the blog on Vercel or GitHub Pages, you will have a Analog repository fork on your GitHub account. Now, clone your repository to your computer.

git clone git@github.com:<your_username>/<your_repository>.git my_blog
cd my_blog

Start the Development Server

You can start the development server with the following command.

yarn install # install NPM dependencies
yarn dev # start the development server

Then you will see console output like this:

/usr/local/bin/yarn run dev
Starting content-collections content-collections.ts
build started ...
... Tag & Category count generated
... finished build of 2 collections and 13 documents in 837ms
start watching ...
  ▲ Next.js 14.2.17 (turbo)
  - Local:        http://localhost:3000

 ✓ Starting...
 ✓ Ready in 1142ms

Open your browser and visit http://localhost:3000 to preview your blog.

Writing Your First Post

By default, Analog will create a demo site with the content in the /data-demo directory. To use your own content directory, you need to set the USER_DATA_DIR environment variable before deploying.

For example, if you want to specify the content directory as data on Vercel, you can set the environment variable in the Vercel dashboard.

After that, you can add a new post by creating a new MDX file in the data/posts directory.

cat << EOF > data/posts/hello-world.mdx
---
title: "Hello, World!"
datePublish: 2024-11-06
summary: "This is the first post of Analog."
---
I am writing my first post with Analog.
EOF

Then you can see the new post on the preview page.

To change the author information, you can modify the file data/authors/default.mdx. You can also remove the default posts and add your own posts. Your local changes need to be pushed to your GitHub repository to deploy.

[!INFO]

The data folder /data-blog is for my personal blog. Just delete it and create your own content folder. You can also use it or the /data-demo folder as a reference.

More Information

You can refer to the Analog User Guide for further information.

• How to Configure it - Set up your blog with your own information.
• How to Create Content - Create your own posts, author pages, and general pages with MDX.
• How to Style it - Restyle your blog with your favorite colors/fonts/widgets/...
• Tech Stack - Learn about the technologies used in Analog.
• Web Analytics Plugin - Integrate web analysis tools like Google Analytics and Umami.
• Comment Plugin - Integrate comment plugins like Disqus, Giscus, and Utterances.

If you have any questions or suggestions, please feel free to open an issue.

Website Structure

The routing structure of the analog website is shown as follows:

/ -------------------- Home
  archive/ ----------- All posts
  posts/
    {slug}/ ---------- Post detail (/data/posts/{slug}.mdx)
  about/ ------------- About, i.e., the default author (/data/about/default.mdx)
    {author}/ -------- Author detail (/data/about/{author}.mdx)
  tags/ -------------- All tags
    {tag}/ ----------- Posts archived by tag
  category/
    {category}/ ------ Posts archived by category
  team/ -------------- Team
  rss.xml ----------- RSS feed
  [others] ---------- General Pages (/data/pages/{others}.mdx)