UXVII
Home Tags About |

Astro Blog Setup Guide:From Scratch to Easy Deployment

Published at 2025-02-08
 Licensed under CC BY-NC-SA 4.0 astroblog

Table of Content

Quickly get started with Astro and build and deploy your high-performance blog from scratch.

Preface: Why Choose Astro?

Astro, as a next-generation static site generator, has become an ideal choice for building content-focused websites due to its unique "component-first" concept and "zero JS by default" feature. Compared to traditional solutions, Astro has the following advantages:

  • Extreme loading performance (pure static HTML generated by default)
  • Flexible component system (supports React/Vue/Svelte components)
  • Content-driven development mode
  • Comprehensive Markdown support
  • Lightweight architecture (project dependencies of only about 100KB)

I. Preparation

1.1 Environment Preparation

node -v
# Check version

1.2 Clone Theme Locally

Different from Hexo, the Astro framework cannot achieve theme switching by simply changing the configuration file. Instead, it requires replacing the entire project file: the theme file is the project file itself. Therefore, choosing a theme in advance is crucial. The following lists some themes that the author prefers for your reference:

fuwari

Koibumi

astro-blur

Clone the theme locally

git clone git@github.com:saicaca/fuwari.git # Take fuwari as an example

1.3 Install Dependencies

pnpm install
pnpm add sharp

At this point, the webpage can be run locally. Start the local server:

npm run dev
# Visit http://localhost:4321

Enter http://localhost:4321 in your browser to access the webpage.

II. Theme Configuration

2.1 File Structure Description (Taking the fuwari theme as an example)

src/
  content/
    config.ts      # Blog configuration
    blog/          # Article directory (example articles)
  layouts/
    PostLayout.astro  # Article layout
 /

2.2 Modify Configuration File

Edit the configuration file src/config.ts to customize your blog. You can modify the file while the blog's local server is running, and the changes will be dynamically updated on the local webpage.

import type {
    LicenseConfig,
    NavBarConfig,
    ProfileConfig,
    SiteConfig,
} from "./types/config";
import { LinkPreset } from "./types/config";

export const siteConfig: SiteConfig = {
    title: "Fuwari", // Website title
    subtitle: "Demo Site", // Website description
    lang: "en", // Language selection 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th'
    themeColor: {
        hue: 250, // Default hue of the theme color, from 0 to 360. For example, red: 0, cyan: 200, teal: 250, pink: 345
        fixed: false, // Whether to hide the theme color picker for visitors
    },
    banner: {
        enable: false, // Whether to enable the banner
        src: "assets/images/demo-banner.png", // Banner path: relative to /src, if relative to /public, it should start with '/'
        position: "center", // Position of the banner image, supported values: 'top', 'center', 'bottom', 'center' is the default option
        credit: {
            enable: false, // Whether to display banner attribution text on the banner image
            text: "", // Attribution text displayed on the banner image
            url: "", // (Optional) Link to the original work or author's page
        },
    },
    toc: {
        enable: true, // Whether to display the table of contents on the right side of the blog
        depth: 2, // Set the maximum heading depth to display in the table of contents (optional range: 1 to 3 levels)
    },
    favicon: [
        // Leave this empty if using the default website icon
        // {
        //   src: '/favicon/icon.png',    // Path to the website icon, relative to the /public directory
        //   theme: 'light',              // (Optional) 'light' or 'dark', only set if different light and dark icons exist in the icon directory
        //   sizes: '32x32',              // (Optional) Icon size, only set if different size icons exist in the icon directory
        // }
    ],
};

export const navBarConfig: NavBarConfig = {
    links: [
        LinkPreset.Home,
        LinkPreset.Archive,
        LinkPreset.About,
        {
            name: "GitHub",
            url: "[https://github.com/saicaca/fuwari](https://github.com/saicaca/fuwari)", // Internal links should not include the base path as it is automatically added
            external: true, // Display an external link icon and open in a new tab
        },
    ],
};

export const profileConfig: ProfileConfig = {
    avatar: "assets/images/demo-avatar.png", // Avatar path: relative to /src, if relative to /public, it should start with '/'
    name: "Lorem Ipsum", // Name
    bio: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", // Bio
    links: [
        {
            name: "Twitter",
            icon: "fa6-brands:twitter", // Visit [https://icones.js.org/](https://icones.js.org/) to get icon codes
            // If the corresponding icon set is not yet included, you need to install it
            // Command: pnpm add @iconify-json/<icon set name>
            url: "[https://twitter.com](https://twitter.com)", // Custom link for the icon
        },
        {
            name: "Steam",
            icon: "fa6-brands:steam",
            url: "[https://store.steampowered.com](https://store.steampowered.com)",
        },
        {
            name: "GitHub",
            icon: "fa6-brands:github",
            url: "[https://github.com/saicaca/fuwari](https://github.com/saicaca/fuwari)",
        },
    ],
};

export const licenseConfig: LicenseConfig = {
    enable: true,
    name: "CC BY-NC-SA 4.0",
    url: "[https://creativecommons.org/licenses/by-nc-sa/4.0/](https://creativecommons.org/licenses/by-nc-sa/4.0/)", // Creative Commons license agreement
};

III. Hosting the Webpage to the Cloud

3.1 Choose a Website Hosting Platform

Building and deploying your Astro site requires choosing a reliable static website hosting platform, such as AWS S3 Static Website Hosting, Vercel, and Cloudflare, etc.

This article uses Vercel as an example. Deployment tutorials for other platforms can be found in the Astro official documentation: Astro Docs.

Use the following astro add command to add the Vercel adapter to your Astro project to enable SSR. This command will install the adapter and automatically configure your astro.config.mjs file accordingly:

npx astro add vercel

3.2 Upload Project Files to Github

  • If you have git tools
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin your_repository_address
git push -u origin main
  • Or directly use Vscode or Github Desktop to commit

3.3 Deploy to Vercel for Hosting

  • Register for a Vercel account
  • Select "Add New" on the right to create a new Project
  • Log in to your Github account and import the blog project repository
  • Set the project name (the project name will be part of the subdomain Vercel assigns to you, e.g., https://project_name.vercel.app/)
  • Deploy and wait patiently
  • Once the webpage hosting is complete, you can log in immediately

Modifying blog files only requires synchronizing them to the Github repository, and Vercel will automatically synchronize and refresh your blog page.

IV. Binding a Domain Name (Optional)

You might find https://project_name.vercel.app/ too unsightly or find that accessing Vercel is unstable in your region. In that case, you can purchase your own domain name for customization.

Vercel supports adding custom domains for redirection.

Domain name purchase: Tencent Cloud Domains Alibaba Cloud Wanwang

  • Open the blog project in Vercel and select "Settings"

  • Select "Domain" and click "Add"

  • Enter the domain name you purchased, and keep the default settings

  • Go to the domain control panel of your domain registrar and add DNS records for the domain:

    Fill in the corresponding value according to the Type prompted by Vercel. Refresh the Domain settings in Vercel, and it should display "Valid Configuration".

    Note: After purchasing a domain name, it takes some time for DNS resolution. Be patient if Vercel shows that the configuration failed initially.

V. Ecosystem Recommendations

Through this guide, you have mastered the core skills to build an Astro blog from scratch. Next, you can:

  1. Try integrating a CMS content management system
  2. Develop custom component libraries
  3. Explore the in-depth application of Astro Islands
  4. Participate in open-source community contributions