The project consists of the following list of files and folders:
/
.astro/
Astro's internal files, this is auto generated and should not be modified.
The most important files here are type definitions, generated by running the command: npm run astro sync.
.github/
GitHub configuration files, the most important files are workflows/astro.yml which builds the project using Github Actions and dependabot.yml which configures dependabot to generate alerts about outdated extensions.
.husky/
Husky is a tool that hooks into git and run commands before actions are made, such as commits and pushes. The files here are simple commands that run before git performs one of those actions.
.vscode/
Visual Studio Code configuration files, including settings, extensions, and launch settings.
The most important file here is settings.json which configures the editor settings. Most settings are for formatting, line ending and using tabs instead of spaces.
certs/
SSL certificates for local development. Those files should be generetad using mkcert following the same instructions on the Setup page.
dist/
The output of npm run build, this is the production build results.
node_modules/
The dependencies of the project. This is generated by npm install.
public/
Static files for the project, those are copied without any processing to the dist/ folder and are available at the root of the site.
Examples of files that are in this folder are favicon.ico and robots.txt. Those have to be accessible on the built project but are not referenced anywhere in the code, so they should be put in the public folder.
src/
The source code of the project.
assets/
Static assets like images, fonts, css, js, and other files that are used in the project.
css/
CSS files of the project.
icons/
Custom icons that are not covered by the libraries for the Icon component.
images/
Images used in the project, like logos.
js/
JavaScript files that are not components, like scripts that run on the client side.
components/
The components used for all pieces that are "more complex than an html tag". Read more about it below.
content/
This folder comes from Astro's structure, it contains all files that will be processed, like blog posts. Read more about it below.
layouts/
Resuable layouts that are used across multiple pages. Read more about it below.
pages/
Pages are the main content of the site, they are the entry points of the site. Read more about it below.
schemas/
The schema definiton for contents. Read more about it below.
utils/
Utility functions that are used across the project. this contains things like functions to sort and organize blog posts that are referenced in multiple places.
env.d.ts
Global typescript type file, used to declare global variables and other things that should be made available throughout the project.
manifest.json
Web App Manifest file, used to configure the PWA part of the project.
sw-caching.ts
Service Worker caching strategies to be used. This is what instructs the service worker on how to cache the site.
.eslintrc
ESLint configuration file, used to configure the linter for JavaScript and TypeScript files.
.stylelintrc
Stylelint configuration file, used to configure the linter for CSS files.
.markuplintrc
Markuplint configuration file, used to configure the linter for HTML and Astro files.
.gitignore
Git configuration file, used to tell git which files to ignore.
astro.config.ts
Astro configuration file, used to configure Astro's behavior.
package.json
NPM configuration file, lists out the project's dependencies and some configuration.
package-lock.json
NPM lock file, used to lock the versions of the dependencies.
tsconfig.json
TypeScript configuration file, used to configure the TypeScript compiler.
README.md
Main documentation for the project.
The components folder contains building blocks for parts that are "more complex than a single html tag". This means parts like:
PostCardthat is used for displaying a card with a blog post summary.Avatarto display an author's picture.PostHeaderused to layout and organize the whole post header.
The layouts folder contain base layouts to use. This means, all the basic structure when you think something like "a page for a blog post", "a page listing blog posts", or "an internal page with content".
All layouts derive from the Base layout and have a similar structure:
- An html header with all the metadata for the page.
- A
<slot>to put the header content before the<main>tag. - The main content inside the
<main>tag. - A footer with content after the
<main>tag.
The pages folder is how the blog is structured when you access it from a browser. That means all URLs for pages are expressed here in some way.
To make dynamic pages work, some files and folders contain square brackets in their names (e.g.: /[year]/[month]/[slug].astro). This is to make use of Astro's Dynamic Routing.
Basically, everything in the square brackets will be replaced and have an html file added during build time with dynamic parameters, sometimes based on collections, like the example below:
/[year]/[month]/[slug].astro -> /2024/01/hello-world/index.html
Contents are the dynamic part that feeds and build all the blog and schemas are the validation for metadata for those collections.
It is based on Astro's Content Collections and contain all the source markdown files for blog posts and authors. Those markdown files will be listed and each one of those will be used as the content to be inserted into the dynamic pages.
For example, if we have the following list of markdown files, each representing a blog post:
hello-world.md, created in January 2024selusa-secundus.md, created in February 2024trivial-triple-triumvirate.md, created in March 2024
Those files, when built, will translate to:
/2024/01/hello-world/index.html/2024/02/selusa-secundus/index.html/2024/03/trivial-triple-triumvirate/index.html
When you have your blog post, like hello-world.md, it's content will be inserted into the [slug].astro file.
In turn, [slug].astro references the layout BlogPost.astro that is for displaying the whole content of a blog post.
Which uses components like AuthorCard, PostHeader and TagList as building blocks.
All together will output the built page.