Skip to content

docs: tailor repository documentation to Herbert Ulrich's personal site #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
heruberuto merged 1 commit into from
Mar 6, 2026
Merged

docs: tailor repository documentation to Herbert Ulrich's personal site #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Code of Conduct

## Our commitment

Participation in this project should be respectful, constructive, and welcoming to everyone.

## Expected behavior

- Be respectful and professional in all interactions.
- Assume good intent and provide actionable feedback.
- Keep discussion focused on improving the project.
- Accept and apply constructive criticism gracefully.

## Unacceptable behavior

- Harassment, hate speech, or personal attacks.
- Trolling, insults, or inflammatory comments.
- Publishing others’ private information without consent.
- Repeatedly derailing discussions away from project goals.

## Scope

This Code of Conduct applies to project spaces, including issues, pull requests, and related discussions.

## Enforcement

Project maintainers may remove, edit, or reject contributions and comments that violate this Code of Conduct.

## Reporting

If you experience or witness unacceptable behavior, open a private issue or contact the maintainer through the contact channel listed on https://bertik.net.

## Attribution

This document is adapted from common open source community standards and tailored for this repository.
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Contributing

Thanks for your interest in improving `bertik.net`.

This repository powers Herbert Ulrich’s personal website, so changes should prioritize correctness, clarity, and maintainability over feature volume.

## What contributions are useful

- typo/grammar fixes
- broken links and metadata fixes
- accessibility improvements
- bug fixes
- build/tooling reliability improvements

## What to avoid without prior discussion

- rewriting personal biography text or publication framing
- adding generic template sections/content
- adding stock/demo images
- broad visual redesigns unrelated to an issue

Please open an issue first for any non-trivial design or content changes.

## Development workflow

1. Fork and create a branch.
2. Make focused changes.
3. Run checks locally:
- `pnpm run lint`
- `pnpm run format:check`
- `pnpm run build`
4. Submit a pull request with a clear description of:
- what changed,
- why it changed,
- how it was verified.

## Content standards

- Keep content specific to Herbert Ulrich and his work.
- Prefer original wording over inherited template language.
- Ensure dates, affiliations, and publication details are accurate.

## Code standards

- Keep changes minimal and scoped.
- Follow existing project style and formatting.
- Do not commit generated artifacts unless explicitly required.

## Questions

If a change touches personal/profile content and intent is unclear, open an issue before implementing.
1 change: 1 addition & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
MIT License

Copyright (c) 2023 Sat Naing
Copyright (c) 2026 Herbert Ulrich

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
201 changes: 54 additions & 147 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,180 +1,87 @@
# AstroPaper 📄
# bertik.net

![AstroPaper](public/astropaper-og.jpg)
[![Figma](https://img.shields.io/badge/Figma-F24E1E?style=for-the-badge&logo=figma&logoColor=white)](https://www.figma.com/community/file/1356898632249991861)
![Typescript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
![GitHub](https://img.shields.io/github/license/satnaing/astro-paper?color=%232F3741&style=for-the-badge)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white&style=for-the-badge)](https://conventionalcommits.org)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=for-the-badge)](http://commitizen.github.io/cz-cli/)
Personal website and publication hub for **Herbert Ulrich**, built with [Astro](https://astro.build/).

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 repository contains the source code for https://bertik.net, including:

Read [the blog posts](https://astro-paper.pages.dev/posts/) or check [the README Documentation Section](#-documentation) for more info.
- a homepage and about page,
- blog-style updates,
- publication entries,
- RSS and SEO metadata,
- generated search index for static search.

## 🔥 Features
## Project purpose

- [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/))
This project is not a reusable website template. It is the maintained source for Herbert Ulrich’s personal web presence.

_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._
Content, wording, and media should stay personal and factual:

## ✅ Lighthouse Score
- no placeholder text,
- no stock “template” copy,
- no generic demo content,
- no unrelated branding.

<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>
## Tech stack

## 🚀 Project Structure
- Astro
- TypeScript
- Tailwind CSS
- Pagefind (static search)

Inside of AstroPaper, you'll see the following folders and files:
## Local development

```bash
/
├── public/
│ ├── pagefind/ # auto-generated when build
│ ├── favicon.svg
│ └── astropaper-og.jpg
├── src/
│ ├── assets/
│ │ ├── icons/
│ │ └── images/
│ ├── components/
│ ├── data/
│ │ └── blog/
│ │ └── some-blog-posts.md
│ ├── layouts/
│ ├── pages/
│ ├── scripts/
│ ├── styles/
│ ├── utils/
│ ├── config.ts
│ ├── constants.ts
│ ├── content.config.ts
│ ├── env.d.ts
│ └── remark-collapse.d.ts
└── astro.config.ts
```

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/data/blog` directory.

## 📖 Documentation

Documentation can be read in two formats\_ _markdown_ & _blog post_.

- Configuration - [markdown](src/data/blog/how-to-configure-astropaper-theme.md) | [blog post](https://astro-paper.pages.dev/posts/how-to-configure-astropaper-theme/)
- Add Posts - [markdown](src/data/blog/adding-new-post.md) | [blog post](https://astro-paper.pages.dev/posts/adding-new-posts-in-astropaper-theme/)
- Customize Color Schemes - [markdown](src/data/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/data/blog/predefined-color-schemes.md) | [blog post](https://astro-paper.pages.dev/posts/predefined-color-schemes/)

## 💻 Tech Stack

**Main Framework** - [Astro](https://astro.build/)
**Type Checking** - [TypeScript](https://www.typescriptlang.org/)
**Styling** - [TailwindCSS](https://tailwindcss.com/)
**UI/UX** - [Figma Design File](https://www.figma.com/community/file/1356898632249991861)
**Static Search** - [FuseJS](https://pagefind.app/)
**Icons** - [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
# pnpm
pnpm create astro@latest --template satnaing/astro-paper

# pnpm
pnpm create astro@latest -- --template satnaing/astro-paper

# yarn
yarn create astro --template satnaing/astro-paper

# bun
bun create astro@latest -- --template satnaing/astro-paper
```

Then start the project by running the following commands:

```bash
# install dependencies if you haven't done so in the previous step.
pnpm install

# start running the project
pnpm run dev
```

As an alternative approach, if you have Docker installed, you can use Docker to run this project locally. Here's how:
The site runs locally at `http://localhost:4321` by default.

```bash
# Build the Docker image
docker build -t astropaper .
## Build

# Run the Docker container
docker run -p 4321:80 astropaper
```bash
pnpm run build
pnpm run preview
```

## Google Site Verification (optional)
`pnpm run build` performs:

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
```
1. Astro type/content checks
2. production build
3. Pagefind indexing
4. copy of the generated search assets into `public/pagefind`

> See [this discussion](https://github.com/satnaing/astro-paper/discussions/334#discussioncomment-10139247) for adding AstroPaper to the Google Search Console.
## Common commands

## 🧞 Commands
| Command | Purpose |
| ----------------------- | -------------------------------------------- |
| `pnpm run dev` | Start local dev server |
| `pnpm run build` | Run checks + build + search index generation |
| `pnpm run preview` | Preview built site |
| `pnpm run lint` | Run ESLint |
| `pnpm run format:check` | Check formatting |
| `pnpm run format` | Apply formatting |
| `pnpm run sync` | Regenerate Astro types |

All commands are run from the root of the project, from a terminal:
## Content locations

> **_Note!_** For `Docker` commands we must have it [installed](https://docs.docker.com/engine/install/) in your machine.
- Main page routes: `src/pages/`
- Posts and publication entries: `src/data/blog/`
- Site-level configuration: `src/config.ts`
- UI building blocks: `src/components/`, `src/layouts/`

| Command | Action |
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm install` | Installs dependencies |
| `pnpm run dev` | Starts local dev server at `localhost:4321` |
| `pnpm run build` | Build your production site to `./dist/` |
| `pnpm run preview` | Preview your build locally, before deploying |
| `pnpm run format:check` | Check code format with Prettier |
| `pnpm run format` | Format codes with Prettier |
| `pnpm run sync` | Generates TypeScript types for all Astro modules. [Learn more](https://docs.astro.build/en/reference/cli-reference/#astro-sync). |
| `pnpm 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 pnpm 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`. |
## Contribution policy

> **_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).
External contributions are welcome for clear fixes (typos, broken links, factual corrections, accessibility improvements, bug fixes).

## ✨ Feedback & Suggestions
For larger structural/content changes, please open an issue first so changes can be aligned with the site owner’s intent.

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.
See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## 📜 License
## Acknowledgement

Licensed under the MIT License, Copyright © 2025
This project was originally bootstrapped from the AstroPaper theme and has since been adapted for Herbert Ulrich’s personal website.

---
## License

Made with 🤍 by [Sat Naing](https://satnaing.dev) 👨🏻‍💻 and [contributors](https://github.com/satnaing/astro-paper/graphs/contributors).
MIT License. See [LICENSE](LICENSE).
Loading