Kremta-Website/docs/project-structure.md

Project Structure

./

Git/GitHub & Project Stuff

• .git is a hidden folder. It is the thing containing all the git tracking. It should never be editied manually. Basically you should just ignore it, it's hidden for a reason.
• .github/ contains GitHub-specific files for the repository. If you want to use Github Pages as a host, you'd put a deployment script in here. However right now it's only purpose is to beg for your money. ...Probably just delete this folder.
• .gitignore is a file that tells git which files and folders not to track. Some of the stuff in the repository you only want to have locally. That could be really big assets, files with sensitive info like keys, etc. You likely won't need to edit this at all.
• README.md is the project README, of course. You can put whatever you want here, it will be displayed on the the repo's page on GitHub.
• LICENSE contains the license details. The MIT license is a good and honorable one. You should not use a more restrictive license than this on the repository overall. As a software license, it doen not apply to the actual content, such as your writings. I added a /terms page where you will be able to outline whatever permissions you want. I have something there for my own site, but I'm no lawyer.

Node Stuff

• Recall, a huge portion of what allows the site to work is node stuff. Your site depends on hundreds of node packages to run.
• package.json is basically a list of your direct node dependencies. This is not meant to be edited directly.
• package_lock.json is basically a list of all your node dependencies. This is very much not meant to be edited directly.
• node_modules contains the dependencies listed in package_lock.json. This is what generated/updated when you run npm install. There's a lot of stuff in here, and NPM makes it easy to install, so we make sure not to track it with Git.

src/

• This folder holds all of your site's source code, plus some other stuff.
• assets/ is where you put all images that will be displayed on the site. Preferably, don't dump every image right in there, make subdirectories. For example, if you keep the blog content collection, make a folder blog, and put any images your blog uses in there. Even make one subdirectory per blog post.
• content/ is where all your content collections live.
  • For uniformity, a collection is defined for each "original content" driven page on the website, even if it's a solitary piece of content, such as the terms or about page.
  • The data type for each content collection is defined in /src/content/config.ts. It will need to be updated if you want to edit the schema of a collection or add a new collection altogether.
  • Once development is pretty much done on your site and you're happy with how everything looks and is structured, the expectation is that you will rarely need to interact with anything outside of this folder (and assets).
• pages/ contains all the pages.
  • The structure of this folder defines the routing structure for your site. So if in the pages folder you have blog/categories/index.astro, you will have that page index.astro located at example.com/blog/categories.
  • The Docs collection actually breaks this rule, because its content is 2 layers deep. I implemented a workaround so the docs pages follow the structure of the content/docs/ folder.
  • The following are artificial constraints made to give a bit more structure and predictability to the astro code:
    • Each file in pages/ will directly reference exactly one page layout, and no other components.
      • A layout is technically just a component, but to maintain a clear project structure, we prefer to treat them as the top-level component within a page.
    • Almost all data is "queried" at this layer. For now, "querying" just refers to a function call, (e.g. getIndex() or getEntries()) that returns a freshly minted copy of one or multiple CollectionEntry objects (which are derived straight from the contents of content/).
    • In this way, we decouple the routing and data querying from the structure/style of the pages themselves. You'd be encouraged to appreciate this design choice and stick to it, unless you specifically have other plans.
• components/ contains all components, which are modular pieces of HTML/CSS/JS. There are three kinds of subdirectory:
  1. [collection]/ contains all layouts and other components specialized to that collection.
     1. EntryLayout defines the structure of a collection entry page.
     2. CollectionLayout defines the structure of the page(s) displaying the collection entries.
  2. common/ contains components that are generic enough to be used across collections.
     • shortcodes/ mainly contains components intended for use directly in .mdx content files.
  3. base/ contains the base layout and associated components. Every other layout in the project is wrapped by base/BaseLayout.astro. Therefore the base layout code is applied to every page on the site.
• TLDR:
  • content holds the actual written content displayed to your site,
  • assets holds the graphics and other resources referenced within content,
  • pages dictates how the site will be traversed and where the data from content gets sent,
  • components is where you give structure and style to the content.

public/

• favicon/ should hold the various forms of your favicon (different devices and contexts will prefer different versions). Favicon.io is a great generator for simple favicons.
• fonts/ holds the actual font files that all text on your site will be displayed in.
  • Use the Google Webfonts Helper to download your fonts. You do not want to be downloading/importing more files than you actually need, so make sure you don't. There's more details here, but I will be happy to help if you need.
• Important note: Whenever you reference an image within the project, the root directory for it is assumed by Astro to be public. That means, for example, if you're writing a blog post and want to pull in an image apple.png, you'd reference it by just "@assets/blog/apple.png", or whichever subdirectory you put it in.
• CNAME must hold the value www.yourdomain.com. Without going into detail, this is necessary to link your domain to the site, and get all the necessary certificates set up.
• robots.txt generally directs web-crawling bots. This one doesn't specify much, but it's fine how it is.
• .htaccess is also probably fine to be left as is.