ASTRO - SSG: Awsome Websites for FREE

Astro is a SSG that… well, before going too technical - Keep reading if:

• You are SelfHosting Wordpress but are tired of the Free Themes offered that everyone is using already.

• You are SelfHosting GHost but you want to try a solution that does not require a Database.

• You want to have your totally Free Portfolio/Blog with Astro on Github Pages

• You want to learn how to tweak an Astro Theme.

The Astro Project

• The Astro Site
• The Astro Source Code at Github
  • License: MIT ❤️

Astro is a relatively new SSG that aims to combine the simplicity of static sites with the power of modern JavaScript frameworks

• Themes: https://astro.build/themes/?search=&price%5B%5D=free
  • https://themesberg.github.io/flowbite-astro-admin-dashboard/

What is Astro?

Astro stands as a beacon of modern web development, empowering developers to craft lightning-fast, scalable, and secure web applications.

Key Features of Astro

Discover the stellar features that set Astro apart:

• Static Site Generation (SSG): Experience the speed and security of static sites, effortlessly generated by Astro.
• Server-Side Rendering (SSR): Elevate your content with dynamic server-side rendering, enhancing SEO and user experience.
• Integration with Popular Frameworks: Seamlessly incorporate Astro into your projects, leveraging the power of React, Vue (and more) to build robust web applications.

Use your favorite JavaScript framework and automatically ship the bare-minimum amount of JavaScript—by default.

Takeaways

Modern Web Development: Astro offers a modern approach to web development, ensuring speed, scalability, and security.
Versatility: From static site generation to server-side rendering, Astro caters to a wide range of development needs.
Integration: With support for leading frameworks, Astro empowers developers to craft exceptional web experiences with ease.

Why Astro?

1. Built on JavaScript: Astro is built on JavaScript, specifically leveraging the Node.js ecosystem. This allows developers to use familiar tools and libraries from the JavaScript ecosystem.
2. Component-based: Astro embraces a component-based architecture, similar to modern JavaScript frameworks like React or Vue.js. This makes it easy to create reusable UI components and build complex user interfaces.
3. Hybrid rendering: One of the key features of Astro is its hybrid rendering approach. It can pre-render static content at build time while also allowing components to hydrate into fully interactive components at runtime. This enables dynamic behavior without sacrificing performance.
4. Framework agnostic: Astro is framework agnostic, meaning you can use it with any JavaScript framework or library of your choice, such as React, Vue.js, Svelte, or even vanilla JavaScript.

Yet another JS framework. Right… but not quite.

It has received recently an update to v4: https://astro.build/blog/astro-4/

• It is a SSG - Similarly to HUGO, it creates static files.
  • The good thing is that JS does not take over unless it is needed in some island (they add interactivity just when is needed - kind of Just in Time for Webs) - which is great for performance
• Astro is library agnostic (React, Solid, Vue, Svelt…or none of them) and we can create many kind of Apps: landing pages, blogs…and recently even with [APIs](#How REST and GraphQL compares?)
• Content-first websites: Fetch data from your CMS or work locally with type-safe Markdown and MDX APIs

• Last but not least, Astro 4 is here

How to use Astro

1. Choose a Theme
2. Tweak the Astro Theme
3. Deploy Astro (Share it online!)

Astro Themes

In general, you can find Astro Free Themes here. You might be interested in the Site Speed.

• https://astro.build/themes/6/?price%5B%5D=free&search=

But you can also find them on Github:

• https://github.com/matt765/Tailcast
• https://github.com/themefisher/bigspring-light-astro

MDX Support

https://docs.astro.build/en/guides/markdown-content/#mdx-features https://docs.astro.build/en/guides/markdown-content/#using-exported-variables-in-mdx

https://mdxjs.com/docs/what-is-mdx/

the theme makes a great summary: https://github.com/isooosi/VisVrs

export const title = 'My first MDX post'

# {title}

# {frontmatter.title}

Simply put - MDX => Leverage: https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx

Deploying Astro

There are several options well documented in their official page: https://docs.astro.build/en/guides/deploy/

I created a step by step guide with the following:

• Github
  • https://docs.astro.build/en/guides/deploy/github/
• Firebase
• Self-Hosting

👉 https://www.youtube.com/watch?v=sOXW0ZnJxbQ

• https://astro.build/themes/
  • https://astro.build/themes/details/supabase-serverside/

Astro + Github Actions to Github Pages

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

The easiest and quickest way to have your project docs or public profile on your Github.

git clone https://github.com/Ladvace/astro-bento-portfolio

#Working Locally?
#npm install
#npm run dev
#localhost:4321

#Ready to Deploy?
#npm run build
#npm install -g serve
#cd dist
#serve

#rm -rf .git
git init
git add .
git commit -m "Initial commit"

git remote add origin https://github.com/JAlcocerT/web3 #<repository-url>
git branch -M main
git push -u origin main

import { defineConfig } from 'astro/config';
import sitemap from "@astrojs/sitemap";
import tailwind from "@astrojs/tailwind";
import { SITE_URL } from './src/site_config';

// https://astro.build/config
export default defineConfig({
  // site: SITE_URL,
  site: 'https://jalcocert.github.io',
  base: '/astrotest/',
  integrations: [tailwind(), sitemap()],
  vite: {
    plugins: [rawFonts(['.ttf'])],
    optimizeDeps: { exclude: ['@resvg/resvg-js'] }
  },
});

function rawFonts(ext) {
  return {
    name: 'vite-plugin-raw-fonts',
    transform(_, id) {
      if (ext.some(e => id.endsWith(e))) {
        const buffer = fs.readFileSync(id);
        return {
          code: `export default ${JSON.stringify(buffer)}`,
          map: null
        };
      }
    }
  };
}

Astro + Firebase

Build locally. Push to Firebase.

Your project files will remain private and you can use your custom domain.

If you are worried about vendor lock-in, you can always check how to SelfHost Static Sites.

npm --version
npm install

npm install -g serve
#serve dist
npm run dev	

npm run build #---> it will be in /dist, not in /public!!!

firebase login
firebase init
firebase deploy

Astro + SelfHosting + Cloudflare

If you want to have everything under your control. This approach is for you.

FROM gitpod/workspace-node

# Install latest pnpm
RUN curl -fsSL https://get.pnpm.io/install.sh | SHELL=`which bash` bash -

# Install deno in gitpod
RUN curl -fsSL https://deno.land/x/install/install.sh | sh
RUN /home/gitpod/.deno/bin/deno completions bash > /home/gitpod/.bashrc.d/90-deno &&     echo 'export DENO_INSTALL="/home/gitpod/.deno"' >> /home/gitpod/.bashrc.d/90-deno &&     echo 'export PATH="$DENO_INSTALL/bin:$PATH"' >> /home/gitpod/.bashrc.d/90-deno

# Use an official Node runtime as the parent image
FROM node:20.12.2-bullseye #18.19-alpine

# Set the working directory in the container
WORKDIR /usr/src/app

# Copy the package.json and package-lock.json (if available) into the container
#COPY package*.json ./


# Install any dependencies
RUN npm install

# Copy the rest of your app's source code into the container
COPY . .

# Build your Astro project
RUN npm run build

# Inform Docker that the container is listening on the specified port at runtime.
EXPOSE 3000

# Define the command to run your app using CMD which defines your runtime
#CMD [ "npm", "start" ]

#docker build -t astro_ssg .
docker build -t astro_ssg -f Dockerfile .

version: '3.8'

services:
  astrp-dev:
    image: astro_ssg:latest
    ports:
      - "8000:8000"
    volumes:
      - app_data:/usr/src/app
      - node_modules:/usr/src/app/node_modules
    environment:
      - NODE_ENV=development
    command: tail -f /dev/null #keep it running      

volumes:
  node_modules:
  app_data:

Tweaking Astro Themes

Getting Started with ASTRO

We need 3 simple steps:

1. To have nodejs installed in the computer https://nodejs.org/en
2. To have a theme selected and cloned in a local folder: https://astro.build/themes/

#git clone https://github.com/web3templates/stablo-astro.git .
git clone https://github.com/web3templates/stablo-astro.git myawsomewebsiteproject

#cd myawsomewebsiteproject
#rm -rf .git

node -v
npm --version
npm install

npm install -g serve
#serve dist
npm run dev	

npm run build 

npm run build #---> it will be in /dist, not in /public!!!

npm install chart.js
npm list chart.js #also in package_lock.json you can see the installed version

npm install chart.js --save

Tweaking an Astro Theme - Example: Tailscast

I found a great theme at https://github.com/matt765/Tailcast, lets have a look how to customize it.

npm install react-ga

// src/analytics.js
import ReactGA from 'react-ga';

export const initGA = (trackingID) => {
  ReactGA.initialize(trackingID);
}

export const logPageView = () => {
  ReactGA.set({ page: window.location.pathname });
  ReactGA.pageview(window.location.pathname);
}

{/*
<div className="grow basis-0 justify-end hidden lg:flex">
  <a
    className="text-white custom-border-gray rounded-xl
    bg-customDarkBg2 hover:bg-customDarkBg3  border-gray-700 pl-6 pr-8 pt-2 pb-2 text-sm flex"
    href="https://github.com/matt765/Tidestream"
    target="_blank"
    aria-label="source code"
  >
    <GithubIcon />
    <span className="pt-px">Source code</span>
  </a>
</div>
*/}

and for mobile

{/*
<a
  className="text-white custom-border-gray rounded-xl
  bg-customDarkBg2 hover:bg-customDarkBg3  border-gray-700 pl-6 pr-8 pt-2 pb-2 text-sm flex"
  href="https://github.com/matt765/Tidestream"
  target="_blank"
>
  <GithubIcon />
  Source code
</a>
*/}

   {/* <div className="w-36 mx-auto lg:mx-0">
                <a
                  className="inline-block w-10  h-10 mr-2 p-2 bg-customDarkBg2 custom-border-gray  hover:bg-gray-700 rounded-xl"
                  href="#"
                >
                  <FacebookIcon />
                </a>
                <a
                  className="inline-block w-10  h-10 mr-2 p-2 bg-customDarkBg2 custom-border-gray  hover:bg-gray-700 rounded-xl"
                  href="#"
                >
                  <TwitterIcon />
                </a>
                <a
                  className="inline-block w-10  h-10 mr-2 p-2 bg-customDarkBg2 custom-border-gray  hover:bg-gray-700 rounded-xl"
                  href="#"
                >
                  <InstagramIcon />
                </a>
              </div> */}

import { MyNewLogo } from "../assets/logos/abcd";

Tweaking Another Astro Theme - BigSpring

• https://github.com/themefisher/bigspring-light-astro
• https://astro.build/themes/details/bigspring-light/

The theme uses Tailwind CSS for styling. You can learn more about Tailwind CSS here: https://tailwindcss.com/.

 <form class="contact-form" method="POST" action={contact_form_action}>
            <div class="mb-3">
              <input
                class="form-input w-full rounded"
                name="name"
                type="text"
                placeholder="Name"
                required
              />
            </div>
            <div class="mb-3">
              <input
                class="form-input w-full rounded"
                name="email"
                type="email"
                placeholder="Your email"
                required
              />
            </div>
            <div class="mb-3">
              <input
                class="form-input w-full rounded"
                name="subject"
                type="text"
                placeholder="Subject"
                required
              />
            </div>
            <div class="mb-3">
              <textarea
                class="form-textarea w-full rounded-md"
                rows="7"
                placeholder="Your message"></textarea>
            </div>
            <button type="submit" class="btn btn-primary"> Send Now</button>
          </form>

Tweaking Astro - Example 3: Ovidius Theme

npm --version
npm install

npm install -g serve
#serve dist
npm run dev	

npm run build 

Tweaking an Astro Theme - Example4: Pacamara

I found a great theme at https://github.com/palmiak/pacamara-astro, lets have a look how to customize it.

git clone https://github.com/palmiak/pacamara-astro pacamara
cd pacamara

#rm -rf .git

npm install

npm start #see changes in dev

npm run build

#firebase --version
firebase init
firebase deploy

Tweaking an Astro Theme - Example 5: StarFunnel

I found a great theme at https://github.com/unfolding-io/StarFunnel, lets have a look how to customize it.

git clone https://github.com/unfolding-io/StarFunnel
rm -rf .git


cd StarFunnel


npm install

#adjust .env (rename env.txt)

npm run dev

#localhost:4321

npm run build # --> ./dist !!!!
npm run preview

npm run build

#firebase --version
firebase init #yourprojectname #dist !!!! #not a single app #not automatic builds & deps #dont overwrite
firebase deploy

FAQ

Deploying Astro to GH Pages

https://docs.astro.build/en/guides/deploy/github/

Modify: astro.config.ts

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import tailwind from '@astrojs/tailwind';

// https://astro.build/config
export default defineConfig({
    site: 'https://jalcocert.github.io',
    base: '/ovidius-astro-theme',
    integrations: [mdx(), sitemap(), tailwind()]
});

name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  # Using a different branch name? Replace `main` with your branch’s name
  push:
    branches: [ main ]
  # Allows you to run this workflow manually from the Actions tab on GitHub.
  workflow_dispatch:

# Allow this job to clone the repo and create a page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v3
      - name: Install, build, and upload your site
        uses: withastro/action@v1
        # with:
          # path: . # The root location of your Astro project inside the repository. (optional)
          # node-version: 18 # The specific version of Node that should be used to build your site. Defaults to 18. (optional)
          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

What it is a headless CMS?

If heard that Astro is compatible with Headless CMS, that’s true. For example with Strapi CMS.

It means that you will be able to interact with some Astro Themes through the CMS to write your content through the UI.

Astro + Strapi

To use Strapi with Astro, you can follow the steps below:

1. First, create a new Strapi project or use an existing one.
2. Next, create a new content type in Strapi and add the fields you need for your Astro site.
3. Then, start your Strapi server and populate your content type with data.
4. In your Astro project, create a new .env file in the root directory and add the following variable: STRAPI_URL="<your-strapi-url>".
5. In your Astro project, install the @astrojs/source-strapi package using npm install @astrojs/source-strapi.
6. In your Astro project, create a new .astro file and import the source-strapi package.
7. Use the source-strapi package to fetch your content from Strapi and render it in your Astro site.

Here is an example of how to use source-strapi in your Astro project:

import { Strapi } from '@astrojs/source-strapi';

export const getStaticPaths = async () => {
  const strapi = new Strapi(process.env.STRAPI_URL);
  const posts = await strapi.getEntries('posts');

  return {
    paths: posts.map((post) => ({
      params: {
        slug: post.slug,
      },
    })),
    fallback: false,
  };
};

export const getStaticProps = async ({ params }) => {
  const strapi = new Strapi(process.env.STRAPI_URL);
  const post = await strapi.getEntry('posts', { slug: params.slug });

  return {
    props: {
      post,
    },
  };
};

export default function Post({ post }) {
  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  );
}

This code fetches the posts content type from Strapi and renders it in your Astro site. You can customize this code to fit your specific needs.

I hope this helps!

What other F/OSS SSGs Alternatives I have?

You can always have a look at jamstack or to this Streamlit App that tracks SSG’s Popularity.

• Gatsby
  • Gatsby loves GraphQL
• HUGO
  • Example Github Pages Project using HUGO
• Jekyll
  • Example Github Pages Project using Jekyll

How to Replace Google Analytics with F/OSS?

• Matomo
• Plausible
• Umami Analytics with Astro - https://fossengineer.com/selfhosting-umami-with-docker/

Add it in the base.astro or baselayout.astro

Here you can also include the sitemap (need to be configured as in VisVrs theme - as dependencies in astro.config.mjs, package-lock.json and package.json)

How REST and GraphQL compares?

REST and GraphQL are two distinct approaches to designing API for exchanging data over the internet.

• REST enables client applications to exchange data with a server using HTTP verbs, which is the standard communication protocol of the internet. RESTful APIs or REST APIs are developed with REST.

• GraphQL is an API query language that defines specifications of how a client application should request data from a remote server. You can use GraphQL in your API calls without relying on the server-side application to define the request. GraphQL APIs are simply GraphQL APIs.

How to Get Better at Astro?

You can have some ideas from:

• https://www.creative-tim.com/learning-lab/astro/switch/astro-launch-ui/
• https://github.com/isooosi/astroverse - it has sample posts explaining a lot about astro, like content collections https://verse-astro.vercel.app/posts/content-collections/

How to Implement Search for Astro Sites

• Using the PageFind static site search.

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructurwe - https://pagefind.app/

https://github.com/cloudcannon/pagefind https://github.com/cloudcannon/pagefind?tab=MIT-1-ov-file#readme

Static low-bandwidth search at scale

The installation process is always the same: Pagefind only requires a folder containing the built static files of your website, so in most cases no configuration is needed to get started.

To Configure Our Astro Site Search with PageFind, we just need:

• https://www.npmjs.com/package/astro-pagefind?activeTab=dependents
  • https://github.com/shishkin/astro-pagefind - MIT Licensed

How to Add Sign In to Astro?

Improving Astro SEO

Astro Site Map

• Make sure to have your sitemap generated and give it to: https://search.google.com/search-console/sitemaps
  • Example Theme with SiteMap - The theme VisVRS: you need to pay attention to: astro.config.mjs, package-lock.json and package.json
  • The NPM JS package we will use: https://www.npmjs.com/package/sitemap - (MIT Licensed ❤️)

  integrations: [
    sitemap(),
    ...
  ]

"@astrojs/sitemap": "^3.1.5",

Astro Robots.txt

Generally, The robots.txt file informs search engines which pages on your website should be crawled.

For Astro project you usually create the robots.txt in a text editor and place it to the public/ directory.

In that case you must manually synchronize site option in astro.config.* with Sitemap: record in robots.txt.

But we can use this npm package instead: https://www.npmjs.com/package/astro-robots-txt#why-astro-robots-txt (MIT Licensed ❤️)

npx astro add astro-robots-txt #npm install astro-robots-txt

It adds it automatically as integrations in your astro.config.mjs and also as dependency at package.json.

Make sure that you have a deployment / site URL for generation in the astro config mjs:

import { defineConfig } from 'astro/config';
import robotsTxt from 'astro-robots-txt';

export default defineConfig({
  site: 'https://example.com',

  integrations: [robotsTxt()],
});

Now just build the site:

astro build #npm run build

And the robots.txt file will be generated at /dist ready to be pushed when deploying the Astro Site

Astro Must Know CLI

npm run dev
npm run build
npm run preview

How to create Presentations with astro

You will be shocked when you discover the power of Astro & RevealJS

Say goodbye to the old ppt’s

• Example - https://jsulpis.github.io/slides-template/#/

• Deploy as simple as: https://github.com/jsulpis/slides-template/blob/main/.github/workflows/deploy.yml with Github Actions

name: Deploy Astro to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write


jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out your repository using git
        uses: actions/checkout@v2

      - name: Use Node.js 18
        uses: actions/setup-node@v2
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build Astro
        run: npm run build --if-present

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

name: Deploy Astro to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out your repository using git
        uses: actions/checkout@v2

      - name: Use Node.js 16
        uses: actions/setup-node@v2
        with:
          node-version: '16'
          cache: 'npm'

      - name: Install dependencies
        run: |
          cd Docs
          npm ci          

      - name: Build Astro
        run: |
          cd Docs
          npm run build --if-present          

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./Docs/dist #THIS IS KEY

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1