Editing this guide

You can actually help improve this website!

These docs are openly available and live on GitHub. If you find an error or have a suggestion for improvement, we encourage you to contribute. Your feedback helps us maintain the highest quality documentation for our users. 🙏

Roadmap

See the open issues for a full list of known issues 🪲 and features that other users have proposed already.

Content contributions

Updating an article

If you simply want to update any of our existing docs:

  • Go to the docs (you’re already there 😊) and browse to the article you want to adjust (just like the page your are reading right now);
  • On the bottom of the page, click “✏︎ Edit page”. You will be redirected to the GitHub editor of this page;
  • Make your edits, but leave the frontmatter (= the text on top of the page between the --- lines) intact;
  • Click the green “Commit changes” button in the top right, add your commit message and click the green sign off button.

Creating a new article

OR, if you want to create a new article:

  • Go to /src/content/docs and select the folder (category) that fits your new article best;
  • In the new folder, create a new .MDX document by clicking “Add file > Create a new file” in the top right;
  • Name your file (ideally the same as the label you use in the frontmatter below);
  • Create your new article, starting with this frontmatter code:
src/pages/post-1.mdx
---
title: Title of your new page
description: Description of your new page
sidebar:
    label: Short name for your page
    order: single or two digit number
---


Your article content goes here.
  1. Click the green “Commit changes” button in the top right, add your commit message and click the green sign off button.

For more information on how to work with Markdown in Astro:

Adding a new section / category

  • Go to /src/content/docs and create a new folder (these act as categories);
  • Add the first article in this new category by following the steps above.\

For more info about routing and the structure of the project, check out the Astro documentation.

Adding an image to an MD(X) file

Upload the image

  • Go to /src/images and on the top right click “Add file” > “Upload files”
  • Drag the file(s) onto your browser or click “choose your files” to upload them.
  • Add a description (just the title is enough), keep other settings and click the green “Sign off and commit changes” button

Embed the image into your document

For .MD files:

Use standard Markdown ![alt](src) syntax in your .md files. This syntax works with Astro’s Image Service API to optimize your local images stored in src/. Remote images and images stored in the public/ folder are not optimized.
Example:

src/pages/post-1.md
# My Markdown Page


<!-- Local image stored in src/assets/ -->
<!-- Use a relative file path or import alias -->
![A starry night sky.](../assets/stars.png)


<!-- Image stored in public/images/ -->
<!-- Use the file path relative to public/ -->
![A starry night sky.](/images/stars.png)


<!-- Remote image on another server -->
<!-- Use the full URL of the image -->
![Astro](https://example.com/images/remote-image.png)
For .MDX files:

If you require more control over your image attributes, we recommend using the .mdx file format, which allows you to include Astro’s <Image /> component or a JSX <img /> tag in addition to the Markdown syntax.

Example:

src/pages/post-1.mdx
---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';


# My MDX Page


// Local image stored in the the same folder
![Houston in the wild](houston.png)


// Local image stored in src/assets/
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)


// Image stored in public/images/
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)


// Remote image on another server
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

Validate if your change actually worked:

  • After your commit, go to the Actions tab and click on the latest action that has the name of your commit.
  • While the website is rebuilding, the status will be orange. Once it’s green, you can check the changes on the live site.
  • If the status turns red, there was an error. You can click on the red cross to see the error message and fix it.

For more details on what you can do with images in Markdown files, check out the Astro documentation.

Code contributions

If you want to go beyond just text changes, please fork the repo and create a pull request. You can also simply open an issue with the tag “bug” or “enhancement”.

  • Fork the Project
  • Create your Feature Branch
  • Commit your Changes
  • Push to the Branch
  • Open a Pull Request

Setup on your local machine

  1. Install (P)NPM or YARN with the links bewlow or install it through Homebrew or Chocolatey.

  2. Setup the project in your favorite code editor like VSCode, Atom, or Sublime Text and clone the repository to your local machine.

  3. Install the project dependencies. Open your terminal, navigate to the project’s root directory, and execute: npm install This command will install all the necessary dependencies defined in the package.json file.

  4. Development Commands

    • npm run dev: Starts a local development server with hot reloading enabled. View your local developement environment at http://localhost:4321
    • npm run preview: Serves your build output locally for preview before deployment.
    • npm run build: Bundles your site into static files for production.
      For detailed help with Astro CLI commands, visit Astro’s documentation.

  5. Go forth and contribute! 🚀

Deployment

Any change to the files in the Github repository will trigger a new deployment. The site is hosted on Github Pages, and the deployment process is automated through GitHub Actions.

Building Your Site locally

Before deployment, you can test the build:

Terminal window
npm run build

This creates a dist/ directory with your built site (configurable via outDir in Astro).

Project Structure

ScrewFast organizes modular components, content, and layouts to streamline development and content management.

src/
├── components/           # Reusable components
│   ├── Meta.astro        # Meta component for SEO
│   ├── sections/         # Components for various sections of the website
│   ├── ThemeIcon.astro   # Component for toggling light/dark themes
│   └── ui/               # UI components categorized by functionality
├── content/              # Markdown files for blog posts, insights, products, and site configuration
│   ├── blog/
│   ├── docs/
│   ├── insights/
│   └── config.ts         # Contains site-wide configuration options
├── data_files/           # Strings stored as JSON files
├── images/               # Static image assets for use across the website
├── layouts/              # Components defining layout templates
│   └── MainLayout.astro  # The main wrapping layout for all pages
├── pages/                # Astro files representing individual pages and website sections
│   ├── 404.astro         # Custom 404 page
│   ├── blog/
│   ├── fr/               # Localized content
│   ├── contact.astro
│   ├── index.astro       # The landing/home page
│   ├── insights/
│   ├── products/
│   ├── robots.txt.ts     # Dynamically generates robots.txt
│   └── services.astro
├── styles/               # CSS styles
└── utils/                # Shared utility functions and helpers

Static Assets and Public Resources

Static files served directly to the browser are within the public directory at the root of the project.

public/
└── scripts/
    └── vendor/
        ├── gsap/ # Animations powered by GSAP (GreenSock Animation Platform)
        │   └── gsap.min.js
        ├── lenis/ # Lenis script for smooth scrolling effects
        │   └── lenis.js
        └── preline/   # Preline UI plugins
            ├── accordion/
            ├── collapse/
            ├── dropdown/
            ├── overlay/
            └── tabs/

The scripts in the public/scripts/vendor directory are essential for the interactivity and aesthetic features of the website. Do not remove these unless you plan to replace their functionality.

Additional Resources

Astro documentation This website is build with Astro, a modern static site generator. There's a ton of info on their documentation site if you want to know more on how to improve this website.