AstroPaper Documentation

repository·main·Indexed 26 days ago

A minimal, responsive, accessible, and SEO-friendly Astro blog theme designed for high performance and customizability. Features include light and dark mode support, static search powered by PageFind, automatic social image generation, and a type-safe content schema using Astro's Content Collections API. Includes guides on installation, configuration of site metadata and blog features, CSS custom properties for color schemes, and migration paths between versions.

Tokens: 16.4K
Snippets: 44
Records: 77
Agent score: 89%

What's inside AstroPaper

Overview of AstroPaper features
main
AstroPaper is a minimal, accessible, and SEO-friendly blog theme built with Astro and Tailwind CSS. It is designed for blogs, portfolios, or documentation sites and includes the following built-in features:
- SEO-friendly architecture
- Fast performance
- Light & dark mode support
- Highly customizable layout
- Organizable blog posts
- Responsive and accessible design
- Static search powered by PageFind
- Automatic social image generation
- Full Markdown support
https://github.com/satnaing/astro-paper/blob/main/src/content/pages/about.md
Update the blog layout width
main
The default blog max-width is 768px (max-w-3xl). To change this, update the max-w-app utility in src/styles/global.css using Tailwind CSS classes.
```
@utility max-w-app {
  @apply max-w-4xl xl:max-w-5xl;
}
```
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/how-to-configure-astropaper-theme.mdx
Update package dependencies using npm-check-updates
main
To efficiently update project dependencies, it is recommended to use the npm-check-updates (ncu) package.
1. Install the tool globally:
  npm install -g npm-check-updates
2. Check for available updates: Run ncu to see a list of all packages that have newer versions available.
3. Update patch dependencies: Patch updates are generally safe. Use either -u to update all automatically or -i to interactively choose packages:
  ncu -u --target patch # OR ncu -i --target patch
4. Update minor dependencies: Minor updates often include new features and are usually safe, but check release notes for breaking changes:
  ncu -i --target minor
5. Update major dependencies: Major updates can break your project. Use the interactive mode to review and update them carefully:
  ncu -i
```
npm install -g npm-check-updates
ncu
ncu -u --target patch
ncu -i --target minor
ncu -i
```
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/how-to-update-dependencies.md
Apply predefined color schemes to AstroPaper
main
To apply a predefined color scheme, copy the CSS variable definitions for the desired scheme into your theme configuration. Light schemes use the :root and [data-theme="light"] selectors, while dark schemes use the [data-theme="dark"] selector.
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/_color-schemes/predefined-color-schemes.mdx

Customize color schemes in AstroPaper

main

Color schemes are defined using CSS variables in src/styles/theme.css. To customize the theme, update the values within the :root, [data-theme="light"] selector for the light theme and the [data-theme="dark"] selector for the dark theme.

Available Color Properties

Property	Definition & Usage
`--background`	Primary color of the website (main background).
`--foreground`	Secondary color of the website (usually text color).
`--accent`	Accent color for links, hover states, and interactive elements.
`--accent-foreground`	Foreground color displayed on top of `--accent` backgrounds.
`--muted`	Muted background color for cards, tags, and hover states.
`--muted-foreground`	Text color displayed on top of `--muted` backgrounds.
`--border`	Border color for dividers and visual separation.

/* Light theme values */
:root,
[data-theme="light"] {
  --background: #fdfdfd;
  --foreground: #282728;
  --accent: #006cac;
  --accent-foreground: #ffffff;
  --muted: #e6e6e6;
  --muted-foreground: #6b7280;
  --border: #ece9e9;
}

/* Dark theme values */
[data-theme="dark"] {
  --background: #212737;
  --foreground: #eaedf3;
  --accent: #ff6b01;
  --accent-foreground: #ffffff;
  --muted: #343f60;
  --muted-foreground: #afb9ca;
  --border: #ab4b08;
}

Customize fonts in AstroPaper

main

AstroPaper uses Astro's fonts API. To replace the default 'Google Sans Code' font with a custom font, you must update the configuration in three specific files: astro.config.ts, src/layouts/Layout.astro, and src/styles/theme.css.

Important: Ensure the font name matches exactly as it appears on Google Fonts. For local fonts or other providers, follow the standard Astro Fonts documentation.

// 1. Update astro.config.ts
import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  // ...
  fonts: [
    {
      name: "Your Font Name",
      cssVariable: "--font-your-font",
      provider: fontProviders.google(),
      fallbacks: ["monospace"],
      weights: [300, 400, 500, 600, 700],
      styles: ["normal", "italic"],
    },
  ],
});

// 2. Update src/layouts/Layout.astro
import { Font } from "astro:assets";

<head>
  <Font
    cssVariable="--font-your-font"
    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
  />
</head>

// 3. Update src/styles/theme.css
@theme inline {
  --font-app: var(--font-your-font);
}

Migrate to Type-safe Frontmatters and Redefined Blog Schema
main
AstroPaper 2.0 uses Astro's Content Collections API to provide type-safe frontmatter. The blog schema is defined in src/content/_schemas.ts. You should use this schema to ensure your markdown files adhere to the required structure.
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/_releases/astro-paper-2.md
Update the AstroPaper template using Git
main
If you are using AstroPaper as a template, you can pull updates from the official repository using Git.
Warning: This method requires knowledge of how to resolve merge conflicts. If you are unsure, manually replace files or only update dependencies.
Important Files to Protect: When updating, do not overwrite your custom content or configurations. The following files/directories typically contain user-specific data:
- src/content/blog/
- src/config.ts
- src/pages/about.md
- public/
- src/styles/base.css
Update Steps:
1. Add the official repository as a remote:
  git remote add astro-paper https://github.com/satnaing/astro-paper.git
2. Create a new branch for the update:
  git checkout -b build/update-astro-paper
3. Pull changes from the official main branch:
  git pull astro-paper main
  Note: If you encounter the error fatal: refusing to merge unrelated histories, use: git pull astro-paper main --allow-unrelated-histories
4. Resolve conflicts: Manually resolve any merge conflicts in your editor, ensuring your custom files (listed above) are preserved.
5. Test and Merge: Thoroughly test your site (articles, components, and customizations) before merging the update branch into your main branch.
```
git remote add astro-paper https://github.com/satnaing/astro-paper.git
git checkout -b build/update-astro-paper
git pull astro-paper main
# If error occurs:
git pull astro-paper main --allow-unrelated-histories
```
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/how-to-update-dependencies.md
Prerequisites for Giscus integration
main
To use Giscus for comments on your static site, ensure the following conditions are met in your GitHub repository:
1. The repository must be public.
2. The Giscus app must be installed on your repository.
3. The Discussions feature must be enabled in your repository settings.
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/how-to-integrate-giscus-comments.md
Add LaTeX support to Astro blog posts
main
To enable LaTeX equation rendering in your AstroPaper Markdown files, you need to install KaTeX and its associated remark/rehype plugins, configure them in astro.config.ts, import the KaTeX CSS in your main layout, and apply typography styling.
1. Install dependencies
Run the following command to install the required packages:
```
pnpm install rehype-katex remark-math katex
```
2. Configure Astro
Update your astro.config.ts to include remarkMath in remarkPlugins and rehypeKatex in rehypePlugins.
3. Import KaTeX CSS
Add the KaTeX CSS stylesheet to your main layout file (e.g., src/layouts/Layout.astro) within the <head> section to ensure equations are styled correctly.
4. Apply Typography Styling
To ensure block equations match your site's theme, add the following rule to src/styles/typography.css:
```
.prose .katex-display {
  @apply text-foreground;
}
```
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/how-to-add-latex-equations-in-blog-posts.md
Store and use images in blog posts
main
You can store images in two locations depending on whether you want Astro to optimize them automatically.
Method 1: Inside src/assets/ (Recommended)
Images stored in src/assets/ are automatically optimized by Astro's Image Service API. You can reference them using a relative path or the @/assets/ alias.
Note: Standard HTML <img> tags or Astro <Image /> components will not work inside standard Markdown files for these assets; use standard Markdown image syntax instead.
Method 2: Inside public/ directory
Images in public/ are served as-is and are not optimized by Astro. You must use absolute paths. You can use either Markdown image syntax or HTML <img> tags.
Warning: Always compress images (e.g., using TinyPng or TinyJPG) before adding them to your project, especially if using the public/ directory, to avoid performance degradation.
```
# Using images in src/assets/ (Optimized)
![something](@/assets/images/example.jpg)

# Using images in public/ (Unoptimized)
![something](/assets/images/example.jpg)
<img src="/assets/images/example.jpg" alt="something">
```
https://github.com/satnaing/astro-paper/blob/main/src/content/posts/adding-new-post.mdx

Configure remark-math and rehype-katex in astro.config.ts

main

Add remarkMath to the markdown.remarkPlugins array and rehypeKatex to the markdown.rehypePlugins array in your Astro configuration file.

import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [
      remarkMath, // [!code ++]
      remarkToc,
      [remarkCollapse, { test: "Table of contents" }],
    ],
    rehypePlugins: [rehypeKatex], // [!code ++]
    shikiConfig: {
      themes: { light: "min-light", dark: "night-owl" },
      wrap: false,
    },
  },
  // ...
});

AstroPaper Documentation

What's inside AstroPaper

Overview of AstroPaper features

Update the blog layout width

Update package dependencies using npm-check-updates

Apply predefined color schemes to AstroPaper

Customize color schemes in AstroPaper

Available Color Properties

Customize fonts in AstroPaper

Migrate to Type-safe Frontmatters and Redefined Blog Schema

Update the AstroPaper template using Git

Prerequisites for Giscus integration

Add LaTeX support to Astro blog posts

1. Install dependencies

2. Configure Astro

3. Import KaTeX CSS

4. Apply Typography Styling

Store and use images in blog posts

Method 1: Inside `src/assets/` (Recommended)

Method 2: Inside `public/` directory

Configure remark-math and rehype-katex in astro.config.ts

AstroPaper Documentation

What's inside AstroPaper

Available Color Properties

1. Install dependencies

2. Configure Astro

3. Import KaTeX CSS

4. Apply Typography Styling

Method 1: Inside src/assets/ (Recommended)

Method 2: Inside public/ directory

Method 1: Inside `src/assets/` (Recommended)

Method 2: Inside `public/` directory