|
| 1 | +## Implementation details |
| 2 | + |
| 3 | +A great care is devoted to a solid, clear, comprehensive, understandable, maintainable and customizable code structure. The intention behind this is to keep things separated, clear, readable and obvious and to reduce complexity and noise. |
| 4 | + |
| 5 | +Below is a more detailed overview of the features and their implementations: |
| 6 | + |
| 7 | +#### Astro |
| 8 | + |
| 9 | +This statically generated, high performance, latest Astro website. It has Post and Project content collections with `.mdx` files and they serve as a main model of the app. Both Tags (1:N) and Categories (1:1) are supported for relations between Posts. View transitions are enabled and posts are animated across all the pages using `transition:name` props. Images are Astro optimized and all image sizes are extracted as reusable constant presets for consistency and reducing overhead. Pagination is available for both Post and Project list pages. Preview mode is available either with `astro preview` script or by setting `PREVIEW_MODE=true` in `.env.production`. RSS and Json feeds are implemented as static API endpoints. There is a React integration for all components that require client side interactivity. |
| 10 | + |
| 11 | +#### Structure |
| 12 | + |
| 13 | +Configurations for integrations and plugins are extracted to keep `astro.config.ts` clean and readable. All website routes are centralized into a single constant object, same for file paths. Layers are separated and organized hierarchically and support both centered and full-width layouts for all types of pages: 1. `.mdx` pages, 2. collections pages - Post and Project, and 3. List pages - indexes with pagination. Querying main application models - Post and Project content collections is extracted into the `/modules` folder for clean and readable `getStaticPaths()`. |
| 14 | + |
| 15 | +#### Styling |
| 16 | + |
| 17 | +There is a support for both light/dark Tailwind modes and color themes with semantic colors. Themes are stored into separate files as CSS variables organized in two levels. Responsive styling is supported for both spacings and typography. All CSS code is organized into three Tailwind layers (base/components/utilities). There is a worked out system for keeping typography styles in sync between markdown content ( `tailwindcss/typography` plugin and `prose` class) and custom components. Typography styles are customized and abstracted into a custom `my-prose` class. Most of component styles are extracted into a CSS files and use `class-variance-authority` for variants. Dynamic class names are implemented using `tailwind-merge` and `clsx`. |
| 18 | + |
| 19 | +#### SEO and Metadata |
| 20 | + |
| 21 | +Metadata is centralized and typed or all types of pages (`.mdx`, collections and lists) with defaults as fallback. There is an API endpoint for generating Open Graph images with hero image and random color gradient using Satori and html template applied to each page. Sitemap is generated at build-time using official integration. Custom styled 404 page is provided. |
| 22 | + |
| 23 | +#### Website |
| 24 | + |
| 25 | +There is an organized assets structure for both optimized (`/src`) and un-optimized (`/public`) images with provided defaults. For icons is used `astro-icon` package supporting both material design (`mdi`) icons and local SVG's. For filtering posts there are the following paginated pages: by tag - `/tags`, by category - `/categories`, by both - `/explore` - Explore (Archive) page. Navbar has items stored as an array and has styled active item for the current route. There is a component for table of contents for blog posts that reads hierarchy of sub-headers from the markdown content. |
| 26 | +A design system with `.mdx` pages is available at the `/design` path, providing a clear preview and debugging of all visual components. Share component for sharing Posts supports Twitter, Facebook, Reddit, LinkedIn and Hackernews. |
| 27 | + |
| 28 | +#### External libraries |
| 29 | + |
| 30 | +Comments are done with Giscus and have dark mode is synced with the main theme. Embedding Tweets, YouTube and Vimeo videos, and Open Graph links is done with `astro-embed`. Syntax highlighting for the embedded code is implemented using `expressive-code`integration. |
| 31 | + |
| 32 | +#### Types and code quality |
| 33 | + |
| 34 | +All code is written in Typescript, types for the entire app are located in a separate folder. There are centralized Zod schemas for Post, Project and Config models with proper defaults to prevent runtime exceptions. Both config and environment variables are typed and build-time validated. There are abstracted types for Post and Project collection models that can include additional fields like calculated reading time. |
| 35 | + |
| 36 | +`tsconfig.json` has defined path aliases for clean and organized imports. Code is formatted using Prettier with sorted imports and ESLint is used for syntax checking. |
| 37 | + |
| 38 | +#### Deployment |
| 39 | + |
| 40 | +Latest git commit info is included in the website footer for easy identification of the currently deployed version. There are three methods for production deployments: 1. Github Pages, 2. Nginx and 3. Docker image and all of them are supported both in Github Actions and locally. Assets copying for Nginx and building Docker images are abstracted into bash scripts and reused in both Github Actions and local deployments for easier local debugging. There is a support for building both `linux/amd64` and `linux/arm64` Docker images. |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +#### Astro |
| 45 | + |
| 46 | +- Latest Astro, statically generated, high performance |
| 47 | +- Post and Project content collections for `.mdx` content |
| 48 | +- Support for both Tags (1:N) and Categories (1:1) relations |
| 49 | +- Astro view transitions that track Post across all the pages |
| 50 | +- Astro optimized images with all image sizes and breakpoints centralized into a single place as constants |
| 51 | +- Pagination for both blog and projects pages |
| 52 | +- Environment variable controlled preview mode for draft posts and projects |
| 53 | +- RSS and Json feed endpoints |
| 54 | +- Enabled React integration for components that require client side interactivity |
| 55 | + |
| 56 | +#### Structure |
| 57 | + |
| 58 | +- Extracted configuration for integrations and plugins to keep `astro.config.ts` clean and readable |
| 59 | +- All website routes centralized into a single constant object |
| 60 | +- All file system paths centralized into a single constant object |
| 61 | +- Clear, separated, hierarchical, both centered and full-width layouts for all types of pages:`.mdx` pages, collections pages - Post and Project, and List pages - indexes with pagination |
| 62 | +- Extracted logic for querying content collections for clean and readable `getStaticPaths()` |
| 63 | + |
| 64 | +#### Styling |
| 65 | + |
| 66 | +- Both dark mode support, light/dark Tailwind modes and color themes support, semantic colors |
| 67 | +- Themes stored into separate files as CSS variables organized in two levels |
| 68 | +- Tailwind responsive styling, both spacings and typography |
| 69 | +- Three layer (base/components/utilities) CSS code organization |
| 70 | +- System for keeping typography styles in sync between markdown (prose) and custom components |
| 71 | +- Customized typography plugin prose class |
| 72 | +- Component styles extracted into CSS files with `class-variance-authority` for variants |
| 73 | +- `tailwind-merge` and `clsx` for dynamic class names |
| 74 | + |
| 75 | +#### SEO and Metadata |
| 76 | + |
| 77 | +- Centralized and typed metadata for all types of pages, with defaults |
| 78 | +- Open Graph image endpoint with Satori template generated images for all pages with hero image and random gradient background |
| 79 | +- Sitemap generated at build-time |
| 80 | +- Custom styled 404 page |
| 81 | + |
| 82 | +#### Website |
| 83 | + |
| 84 | +- Organized assets structure for both optimized (`/src`) and un-optimized (`/public`) images with extracted defaults |
| 85 | +- `astro-icon` package supporting both material design (`mdi`) icons and local SVG's |
| 86 | +- Paginated list pages for filtering posts: by tag - `/tags`, by category - `/categories`, by both - `/explore` - Explore (Archive) page |
| 87 | +- Collapsible navbar with items stored as array and active item for the current route |
| 88 | +- Table of contents for blog posts |
| 89 | +- Design system with `.mdx` pages available at `/design` path for clear preview and debugging of all visual components |
| 90 | +- Share component supporting Twitter, Facebook, Reddit, LinkedIn and Hackernews |
| 91 | + |
| 92 | +#### External libraries |
| 93 | + |
| 94 | +- Comments with Giscus and dark mode support |
| 95 | +- `astro-embed` for embedding tweets, YouTube and Vimeo videos, and Open Graph links |
| 96 | +- Embedded code syntax highlighting using `expressive-code`integration |
| 97 | + |
| 98 | +#### Types |
| 99 | + |
| 100 | +- Fully Typescript, all types are located in a separate folder |
| 101 | +- Centralized Zod schemas for Post, Project and Config models with proper defaults to prevent runtime exceptions |
| 102 | +- Fully typed and build-time validated config and environment variables |
| 103 | +- Abstracted Post and Project collection models that can include additional fields like calculated reading time |
| 104 | + |
| 105 | +#### Development |
| 106 | + |
| 107 | +- Typescript path aliases for clean and organized imports |
| 108 | +- Prettier formatting with sorted imports |
| 109 | +- ESLint syntax checking |
| 110 | + |
| 111 | +#### Deployment |
| 112 | + |
| 113 | +- Latest git commit info is included in the website footer for easy identification of the currently deployed version |
| 114 | +- Production deployments with Github Pages, Nginx and Docker image |
| 115 | +- All three deployment methods are supported both in Github Actions and locally |
| 116 | +- The same bash scripts reused for both Github Actions and local deployments for easy debugging locally |
| 117 | +- Support for building both `x86` and `arm` Docker images |
0 commit comments