188 lines
10 KiB
Markdown
188 lines
10 KiB
Markdown
# AstroPaper 📄
|
|
|
|
|
|
[](https://www.figma.com/community/file/1356898632249991861)
|
|
|
|
|
|
[](https://conventionalcommits.org)
|
|
[](http://commitizen.github.io/cz-cli/)
|
|
|
|
AstroPaper is a minimal, responsive, accessible and SEO-friendly Astro blog theme. This theme is designed and crafted based on [my personal blog](https://satnaing.dev/blog).
|
|
|
|
This theme follows best practices and provides accessibility out of the box. Light and dark mode are supported by default. Moreover, additional color schemes can also be configured.
|
|
|
|
This theme is self-documented \_ which means articles/posts in this theme can also be considered as documentations. Read [the blog posts](https://astro-paper.pages.dev/posts/) or check [the README Documentation Section](#-documentation) for more info.
|
|
|
|
## 🔥 Features
|
|
|
|
- [x] type-safe markdown
|
|
- [x] super fast performance
|
|
- [x] accessible (Keyboard/VoiceOver)
|
|
- [x] responsive (mobile ~ desktops)
|
|
- [x] SEO-friendly
|
|
- [x] light & dark mode
|
|
- [x] fuzzy search
|
|
- [x] draft posts & pagination
|
|
- [x] sitemap & rss feed
|
|
- [x] followed best practices
|
|
- [x] highly customizable
|
|
- [x] dynamic OG image generation for blog posts [#15](https://github.com/satnaing/astro-paper/pull/15) ([Blog Post](https://astro-paper.pages.dev/posts/dynamic-og-image-generation-in-astropaper-blog-posts/))
|
|
|
|
_Note: I've tested screen-reader accessibility of AstroPaper using **VoiceOver** on Mac and **TalkBack** on Android. I couldn't test all other screen-readers out there. However, accessibility enhancements in AstroPaper should be working fine on others as well._
|
|
|
|
## ✅ Lighthouse Score
|
|
|
|
<p align="center">
|
|
<a href="https://pagespeed.web.dev/report?url=https%3A%2F%2Fastro-paper.pages.dev%2F&form_factor=desktop">
|
|
<img width="710" alt="AstroPaper Lighthouse Score" src="AstroPaper-lighthouse-score.svg">
|
|
<a>
|
|
</p>
|
|
|
|
## 🚀 Project Structure
|
|
|
|
Inside of AstroPaper, you'll see the following folders and files:
|
|
|
|
```bash
|
|
/
|
|
├── public/
|
|
│ ├── assets/
|
|
│ │ └── logo.svg
|
|
│ │ └── logo.png
|
|
│ └── favicon.svg
|
|
│ └── astropaper-og.jpg
|
|
│ └── robots.txt
|
|
│ └── toggle-theme.js
|
|
├── src/
|
|
│ ├── assets/
|
|
│ │ └── socialIcons.ts
|
|
│ ├── components/
|
|
│ ├── content/
|
|
│ │ | blog/
|
|
│ │ | └── some-blog-posts.md
|
|
│ │ └── config.ts
|
|
│ ├── layouts/
|
|
│ └── pages/
|
|
│ └── styles/
|
|
│ └── utils/
|
|
│ └── config.ts
|
|
│ └── types.ts
|
|
└── package.json
|
|
```
|
|
|
|
Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
|
|
|
|
Any static assets, like images, can be placed in the `public/` directory.
|
|
|
|
All blog posts are stored in `src/content/blog` directory.
|
|
|
|
## 📖 Documentation
|
|
|
|
Documentation can be read in two formats\_ _markdown_ & _blog post_.
|
|
|
|
- Configuration - [markdown](src/content/blog/how-to-configure-astropaper-theme.md) | [blog post](https://astro-paper.pages.dev/posts/how-to-configure-astropaper-theme/)
|
|
- Add Posts - [markdown](src/content/blog/adding-new-post.md) | [blog post](https://astro-paper.pages.dev/posts/adding-new-posts-in-astropaper-theme/)
|
|
- Customize Color Schemes - [markdown](src/content/blog/customizing-astropaper-theme-color-schemes.md) | [blog post](https://astro-paper.pages.dev/posts/customizing-astropaper-theme-color-schemes/)
|
|
- Predefined Color Schemes - [markdown](src/content/blog/predefined-color-schemes.md) | [blog post](https://astro-paper.pages.dev/posts/predefined-color-schemes/)
|
|
|
|
> For AstroPaper v1, check out [this branch](https://github.com/satnaing/astro-paper/tree/astro-paper-v1) and this [live URL](https://astro-paper-v1.astro-paper.pages.dev/)
|
|
|
|
## 💻 Tech Stack
|
|
|
|
**Main Framework** - [Astro](https://astro.build/)
|
|
**Type Checking** - [TypeScript](https://www.typescriptlang.org/)
|
|
**Component Framework** - [ReactJS](https://reactjs.org/)
|
|
**Styling** - [TailwindCSS](https://tailwindcss.com/)
|
|
**UI/UX** - [Figma Design File](https://www.figma.com/community/file/1356898632249991861)
|
|
**Fuzzy Search** - [FuseJS](https://fusejs.io/)
|
|
**Icons** - [Boxicons](https://boxicons.com/) | [Tablers](https://tabler-icons.io/)
|
|
**Code Formatting** - [Prettier](https://prettier.io/)
|
|
**Deployment** - [Cloudflare Pages](https://pages.cloudflare.com/)
|
|
**Illustration in About Page** - [https://freesvgillustration.com](https://freesvgillustration.com/)
|
|
**Linting** - [ESLint](https://eslint.org)
|
|
|
|
## 👨🏻💻 Running Locally
|
|
|
|
You can start using this project locally by running the following command in your desired directory:
|
|
|
|
```bash
|
|
# npm 6.x
|
|
npm create astro@latest --template satnaing/astro-paper
|
|
|
|
# npm 7+, extra double-dash is needed:
|
|
npm create astro@latest -- --template satnaing/astro-paper
|
|
|
|
# yarn
|
|
yarn create astro --template satnaing/astro-paper
|
|
|
|
# pnpm
|
|
pnpm dlx create-astro --template satnaing/astro-paper
|
|
```
|
|
|
|
> **_Warning!_** If you're using `yarn 1`, you might need to [install `sharp`](https://sharp.pixelplumbing.com/install) as a dependency.
|
|
|
|
Then start the project by running the following commands:
|
|
|
|
```bash
|
|
# install dependencies
|
|
npm run install
|
|
|
|
# start running the project
|
|
npm run dev
|
|
```
|
|
|
|
As an alternative approach, if you have Docker installed, you can use Docker to run this project locally. Here's how:
|
|
|
|
```bash
|
|
# Build the Docker image
|
|
docker build -t astropaper .
|
|
|
|
# Run the Docker container
|
|
docker run -p 4321:80 astropaper
|
|
```
|
|
|
|
## Google Site Verification (optional)
|
|
|
|
You can easily add your [Google Site Verification HTML tag](https://support.google.com/webmasters/answer/9008080#meta_tag_verification&zippy=%2Chtml-tag) in AstroPaper using an environment variable. This step is optional. If you don't add the following environment variable, the google-site-verification tag won't appear in the HTML `<head>` section.
|
|
|
|
```bash
|
|
# in your environment variable file (.env)
|
|
PUBLIC_GOOGLE_SITE_VERIFICATION=your-google-site-verification-value
|
|
```
|
|
|
|
> See [this discussion](https://github.com/satnaing/astro-paper/discussions/334#discussioncomment-10139247) for adding AstroPaper to the Google Search Console.
|
|
|
|
## 🧞 Commands
|
|
|
|
All commands are run from the root of the project, from a terminal:
|
|
|
|
> **_Note!_** For `Docker` commands we must have it [installed](https://docs.docker.com/engine/install/) in your machine.
|
|
|
|
| Command | Action |
|
|
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `npm install` | Installs dependencies |
|
|
| `npm run dev` | Starts local dev server at `localhost:4321` |
|
|
| `npm run build` | Build your production site to `./dist/` |
|
|
| `npm run preview` | Preview your build locally, before deploying |
|
|
| `npm run format:check` | Check code format with Prettier |
|
|
| `npm run format` | Format codes with Prettier |
|
|
| `npm run sync` | Generates TypeScript types for all Astro modules. [Learn more](https://docs.astro.build/en/reference/cli-reference/#astro-sync). |
|
|
| `npm run lint` | Lint with ESLint |
|
|
| `docker compose up -d` | Run AstroPaper on docker, You can access with the same hostname and port informed on `dev` command. |
|
|
| `docker compose run app npm install` | You can run any command above into the docker container. |
|
|
| `docker build -t astropaper .` | Build Docker image for AstroPaper. |
|
|
| `docker run -p 4321:80 astropaper` | Run AstroPaper on Docker. The website will be accessible at `http://localhost:4321`. |
|
|
|
|
> **_Warning!_** Windows PowerShell users may need to install the [concurrently package](https://www.npmjs.com/package/concurrently) if they want to [run diagnostics](https://docs.astro.build/en/reference/cli-reference/#astro-check) during development (`astro check --watch & astro dev`). For more info, see [this issue](https://github.com/satnaing/astro-paper/issues/113).
|
|
|
|
## ✨ Feedback & Suggestions
|
|
|
|
If you have any suggestions/feedback, you can contact me via [my email](mailto:contact@satnaing.dev). Alternatively, feel free to open an issue if you find bugs or want to request new features.
|
|
|
|
## 📜 License
|
|
|
|
Licensed under the MIT License, Copyright © 2023
|
|
|
|
---
|
|
|
|
Made with 🤍 by [Sat Naing](https://satnaing.dev) 👨🏻💻 and [contributors](https://github.com/satnaing/astro-paper/graphs/contributors).
|