Astro

This tutorial will guide you through creating an Astro site with a Home page, a Blog section, and an About page.

What is Astro?

Astro is a fast and flexible website builder that deploys as static pages, meaning it creates practically zero load on your HelioHost account.

This tutorial offers an alternative method for creating a website or blog, designed for users who want to avoid the risk of account suspension due to high server load from other blog creation apps.

Unlike WordPress, which runs PHP code and queries a database on every visit, increasing your account load even more with plugins and heavy themes, Astro keeps things lightweight and efficient. Since Astro generates static pages in advance, your site loads instantly and won't carry the same risk of account suspension like WordPress sites often do.

System Requirements

This tutorial has been created on Windows 11 without WSL (Windows Subsystem for Linux) installed. However, Windows users with WSL/WSL2 and Linux users should also be able to follow the steps below, using the equivalent commands for their system.

Before continuing with this tutorial, please visit the links above and install VS Code and the latest LTS (Long-Term Support) version of Node.js.

About VS Code

Visual Studio Code, usually called VS Code (or VSCode), is a free IDE (Integrated Development Environment). It's a popular choice for developers since it offers debugging support, code syntax highlighting, intelligent code completion, embedded Git/GitHub version control, different color themes, extensions, and more.

This tutorial will use VS Code's text editing functionality, the built-in file explorer menu, and the built-in terminal command line.

Note: VS Code is a different product than the very similarly-named 'Visual Studio' app.

About Node.js

Node is a free and open-source JavaScript runtime environment. As a HelioHost user, you may already know that Node apps often require a lot of server resources. Running a Node app on our shared hosting servers can risk your account being suspended for high server usage on Tommy and Johnny or charged for overages on Morty.

In this tutorial, Node will run Astro in a development environment on your local computer, not HelioHost's servers. We will also use Node to run the build process, converting your Astro project into a static site to upload to your HelioHost account file storage. This tutorial only runs Node on your local machine.

During the Node.js install process, you may be asked about installing 'Tools for Native Modules'. You can leave the checkbox unchecked and click on the 'Next' button.

Nice to Have

Knowledge of basic Linux commands such as cd or mkdir
An understanding of Markdown syntax so you can customize your site content

Getting Started

Open VS Code

To begin building your Astro site, first open VS Code. If this is your first time using VS Code, you will see a 'Walkthrough: Setup VS Code' page, offering the chance to set up Copilot, choose a theme, etc. These steps are not needed for this tutorial, so click on the 'Mark Done' link.

You will then see a 'Welcome' page where you can optionally uncheck the 'Show welcome page on startup' box and close the Welcome page by clicking on the 'X' on the file tab.

Open the VS Code Terminal

Inside VS Code, navigate to: Terminal > New Terminal

You should see the terminal window at the bottom of your VS Code app.

Change the terminal type from 'PowerShell' to 'Command Prompt' by clicking on the little down arrow on the right side of the terminal to open the selection menu and choose 'Command Prompt'.

You should see the 'cmd' terminal line highlighted, confirming it is active and selected.

Confirm that Node.js is Installed

Enter the code below into your cmd terminal window, and press Enter: node -v

If Node.js has been installed correctly, you should see a message confirming the Node version number:

Create a New Astro Site

Astro is highly customizable, but we will use their premade blog site template for this tutorial. If you wish to navigate to a different directory, you can use the Linux command cd. However, we will create our Astro site project inside the Windows user system directory for this tutorial.

Note: You do not need to create a new directory for your Astro project. This will be handled as part of the Astro site creation process.

Paste the following code into the VS Code cmd terminal and press Enter:

npm create astro -- --template blog

You will be asked if it's OK to install the create-astro@[current-version] package. You can type in y and press enter, or just press enter since the y (yes) answer is the default.

You will be asked, 'Where should we create your new project?' and Astro will suggest a random folder name, as shown in the screenshot below. The name you choose for this folder will only be known to you, it will never be seen by your website visitors. If you want to use the folder name Astro suggests, press Enter. If you prefer to name your folder something else, type in the name you want to use, and press Enter. We'll create a folder for this tutorial called my-blog.

You will be asked 'Install dependencies? (recommended)'. The Yes option should be selected by default. If not, use the left and right arrow keys to select Yes and press Enter.

You will be asked 'Initialize a new git repository? (optional)'. The choice is up to you, since git is not used in this tutorial. Git is a useful tool for version control, allowing you to track changes and revert to previous versions if needed. If you're interested in learning Git later, it's a good idea to select Yes now so it's set up in advance for you.

You will see status updates in the terminal as the installation progresses, and finally, a 'Liftoff confirmed' message indicating that the installation has finished.

Explore Project Files

As it said in the install confirmation message, we can use the command cd ./my-blog (or cd my-blog) to navigate into the 'my-blog' project folder.

Once inside the 'my-blog' folder, enter the command npm run dev into your cmd terminal window to start running Astro on your local machine.

To take a first look at the site created, open a web browser window and go to http://localhost:4321 (or press Ctrl + Click on the link provided in the terminal) to open the site on your local machine.

If everything was done correctly, you should see the 'Hello, Astronaut!' page in your browser.

Editing the Astro Site

Go back into VS Code and click on the square 'Explorer' button. Click on the blue 'Open Folder' button.

Find and Open the Astro Site Folder

Locate the 'my-blog' folder (or whatever you named yours) on your machine, click the folder to highlight it, and then click on the 'Select Folder' button to open it.

You may see a popup window asking 'Do you trust the authors of the files in this folder?'. Click on the blue 'Yes, I trust the authors' button.

You may see a popup window asking 'Do you want to install the recommended extensions from Astro and unified for this repository?'. Click the 'X' to close the suggestion window. (We do not need the extensions to follow this tutorial, but it's not a problem if you decide to install them.)

If you did not uncheck the 'Show welcome page on startup' earlier in this tutorial, you will see the Welcome page again. Click on the 'X' in the tab window to close the Welcome screen.

You should see your files along the left side menu bar inside VS Code.

Restart the Astro Site running on LocalHost

You will probably need to reopen the Terminal, so once again go to: Terminal > New Terminal

As we did earlier, change the Terminal type again from 'PowerShell' to 'Command Prompt' by clicking on the little down arrow on the right side of the terminal to open the selection menu and choose 'Command Prompt'.

Once again, you should see the cmd terminal line highlighted, confirming it is active and selected.

In the cmd terminal window, enter the command npm run dev to start Astro running again on your local machine.

Open a web browser window and go to http://localhost:4321 (or press Ctrl + Click on the link shown in the terminal) to open the site on your local machine.

Once again, if everything was done correctly, you should see the 'Hello, Astronaut!' page in your browser.

Editing Your Site

Guidance is provided on the 'Hello, Astronaut!' page about where to find some files you may wish to edit, and we encourage you to explore and experiment as you work through the list.

Since this is a tutorial about making a site with a blog, we will jump right to the 4th list item: 'Check out the included blog posts in src/content/blog/' and create a new blog post.

Create a New Blog Post File

Using the left side file explorer menu inside VS Code, go to: src > content > blog

Right click on the 'blog' folder and choose the 'New File' option.

Name the new file hello-world.md.

Note: '.md' files are Markdown files. You do not need to know Markdown syntax to follow this tutorial, but Astro offers a helpful Markdown Style Guide if you want to learn more about how to customize your site with bold or italic text or to insert headers, images, or web links.

Astro Detected an Unhandled Rejection

You may notice on your site and in your terminal window that Astro crashed with an error right after we created the new 'hello-world.md' file. We will fix this issue next.

The part of the error that explains best what happened is:

InvalidContentEntryDataError: blog → hello-world data does not match collection schema. title: Required description: Required pubDate: Invalid date

What the error message means is that Astro is expecting a 1) title, 2) description, and 3) pubDate (publication date) inside our new file. When Astro is running, it continually monitors all your project files. When we created the empty hello-world.md file, it have the contents Astro expected, so it threw an error.

Optional: Have a look at the top sections of the existing files inside the src/content/blog folder for some examples of the details Astro expects at the top of blog post files.

Edit the New Blog Post File

We will now update the 'hello-world.md' file to resolve the error. At the top of the empty 'hello-world.md' file, paste in the following code. (For the date, use the current date with 'single quotes' around it, as shown in the example below):

---
title: 'HelioHost Rocks'
description: 'My new blog on HelioHost'
pubDate: 'Mar 02 2025'
heroImage: '/blog-placeholder-about.jpg'
---

## Welcome to My Blog

This is my blog, hosted on HelioHost!

The 'heroImage' item is optional, but has been included as an example of how to link your own images once you've added them to the project folder.

Save the 'hello-world.md' file by going to: File > Save (or pressing Ctrl +S)

Check your terminal console, and you should see that the error is gone and Astro has reloaded.

View Your Site

Check your site running in the browser at http://localhost:4321, and you should see the error is gone.

Click on the 'Blog' link, and you should see the below:

Click on the image or the 'HelioHost Rocks' title to view your blog post:

Deploy Your Astro Site

Next, let's publish this site and share it with the world. Right now, Astro is running your site in a development environment on your local machine because of the npm run dev command we ran. This is a useful way to develop the site since it ensures that code changes appear instantly without needing to refresh your site in the local browser.

To deploy the site so everyone on the internet can see it, we will need to 1) build a production-ready version and 2) deploy the site to a HelioHost hosting account.

Build the Production Site

Inside the VS Code cmd terminal window, press Control + C to stop Astro from running on local host. It will ask you 'Terminate batch job (Y/N)?', so enter Y for yes, and press Enter.

Type the following code into your cmd terminal, and press Enter:

npm run build

It may take a minute or two to finish, but you will see progress updates inside the terminal. Once the site has been built, a new folder called 'dist' will be created, and you will see a 'Complete!' message in the terminal.

Upload the Astro Site to HelioHost

To publish the Astro site, you will upload everything inside the dist folder (but not the dist folder itself) to your HelioHost account. You can either use an FTP client like FileZilla or the Plesk File Manager. In the example below, we will use Plesk's built-in file manager.

Login to HelioHost and go to: Plesk > Websites & Domains [domain] > Dashboard > Files

Make sure you are inside your httpdocs folder inside Plesk. Select all the files and folders inside the Astro dist folder on your machine, and drag and drop them into httpdocs.

It may take a minute or two to finish, but you will see a confirmation message in Plesk once all the files have successfully been uploaded.

Visit Your HelioHost Site

Visit your website at 'domain.helioho.st', and if everything has been done correctly, you should see the 'Hello, Astronaut!' main page. Click on the 'Blog' link in the header, and you should see the list of blog posts, with the 'HelioHost Rocks' post shown at the top. Clicking on the image or the 'Hello World' title should show you that specific blog post.

Update Your Site

To add more blog posts, or to update the 'Home' or 'About' pages, the process will be similar to what we've already done above:

Open your project folder inside VS Code
Open the Terminal, switch the terminal type to 'cmd', and run the npm run dev command
Open a browser window to view the Astro site running on your local machine at http://localhost:4321
Create new files, or edit existing files, making sure to Save your changes
Stop your development environment in the terminal with Ctrl + C and then answer Yes to stop the batch job
Build your updated site by typing npm run build into the terminal window
Upload the entire contents Astro's dist folder into your httpdocs folder in Plesk on your HelioHost account

Further Self-Learning

Now that you know how to add more blog posts, some other quick ways to personalize your Astro site even more are:

Finish the list of suggestions on the Astro Home page, such as:
- Edit the Home page in src/pages/index.astro
- Edit the site header items in src/components/Header.astro
- Add your name to the site footer in src/components/Footer.astro
Edit your site title (shown in your browser tab) and site description in the src\consts.ts file
Delete the default example blog posts from the src\content\blog folder
- Optional: You could keep the 'markdown-style-guide.md' file if you want a quick reference guide for Markdown, but Astro host the same Markdown Style Guide on their site.
- Optional: You could keep the 'using-mdx.mdx' file to learn more about MDX, but Astro host the same Using MDX guide on their site.

Further Support

If you cannot view your published site after following the above steps, please go back and check every step again to make sure nothing was missed. After doing this, if you are still stuck, please feel free to post a new topic in the Customer Support forum. Make sure you provide your hosting account username and details of the problem, including any error messages received.