User Guide

Unlike most of our templates, Folio can be used by people who need a light Blog, who are not familiar with coding, or don't want to run resource consuming CMS platforms like WordPress.

A CMS alternative

Folio is a project that you can use to build a minimal and elegant Blog in no time, with minimal coding knowledge. Folio is powered by Astro, a powerful javascript framework to shaped for content driven websites. You don't need to have a heavy installation, plugins or anything else. Using Folio, you focus solely on content by writing markdown files for your blog posts. Using the same markdown files, you can add valuable data to your articles, such as categories, tags, information about the author and more.

The theme has been thought and built on a solid layout proposition, and we made sure you can build a very decent blog with the default setup. The following guide is focused on using the provided default theme. If you need to customize the layouts and the components, please refer to the next sections of the documentation.

Setting up the project

Although no coding knowledge is required, you will still need to setup the theme on your local computer to make changes in the configuration and add content. This project needs to be compiled before being uploaded and set on your hosting. Each time changes are made (e.g: add new blog posts, new categories, new authors), the theme needs to be recompiled before pushing the update to the live version. There are many ways to proceed. Here is what some people would do, based on their coding knowledge. The starting point should always be the creation of a GitHub repository to hold your project, for obvious backup reasons. You can:

• Update the theme locally, on your computer. Build it locally and upload the dist files to your hosting using FTP or other means.
• Use your GitHub account with a deployment provider like Netlify to build your project and deploy the update to the production server.
• Use your GitHub account with a custom CI script to build and deploy your changes.

To install the project and its dependencies please refer to the template highlights section of the documentation.

Configuring the theme

Before you can start adding content, you first need to configure the theme. The configuration options can be edited on the src/config.ts file.

Site metadata

The config.ts file starts with a Typescript declaration of the website metadata, such as the website title, description, author and organization. You can then reuse this data anywhere in the project, but this more of a developer feature.

export const SiteMetadata = {
  title: 'Folio',
  description: 'An Astro starter for blog and portfolio websites.',
  author: {
    name: 'CSS Ninja',
    twitter: '@cssninjaStudio',
    url: 'https://cssninja.io',
    email: 'hello@cssninja.io',
    summary: 'CSS Ninja is a web design studio. We build handcrafted and polished templates that will give some hype to your brand. Let\'s start building awesome apps!',
  },
  org: {
    name: 'cssninja.io',
    twitter: '@cssninjaStudio',
    url: 'https://cssninja.io',
    email: 'hello@cssninja.io',
    summary:
      'CSS Ninja is a web design studio. We build handcrafted and polished templates that will give some hype to your brand. Let\'s start building awesome apps!',
  },
  location: 'United States',
  latlng: [-33.86785, 151.20732] as [number, number],
  repository: 'https://github.com/cssninjaStudio/folio',
  social: [
    {
      name: 'LinkedIn',
      link: 'https://www.linkedin.com/company/cssninja/',
      icon: 'linkedin',
    },
    {
      name: 'Facebook',
      link: 'https://www.facebook.com/cssninjaStudio',
      icon: 'facebook',
    },
    {
      name: 'Twitter',
      link: 'https://twitter.com/cssninjaStudio',
      icon: 'twitter',
    },
    {
      name: 'GitHub',
      link: 'https://github.com/cssninjaStudio',
      icon: 'github',
    },
  ],
  buildTime: new Date(),
}

Edit the information in this object to match your details and your organization. This will be injected within the build and generate your details and social links in the website footer.

Site logo and default images

You also need to set some default images for your site, including the logo.

export const Logo = '/svg/logo/logo.svg'
export const LogoImage = '/images/logo.png'
export const FeaturedSVG = '/svg/illustrations/scenses/draw-1.svg'
export const DefaultSVG = '/svg/illustrations/scenses/draw-1.svg'
export const DefaultImage = '/images/posts/1.png'

Either replace the files with your own files or change the paths to your own files.

WARNING

These images are part of the build process, as they are resolved and served dynamically. Dynamic images should always reside in src/images or in the src/svg folder for vector images. Static images can be added to the /public directory.

Navigation links

Template navigation is programmatically rendered based on the config.ts file content. To change the links in the navbar or in the mobile sidebar, edit the NavigationLinks section of the config.ts file:

export const NavigationLinks = [
  { name: 'Home', href: '/home' },
  { name: 'Blog', href: '/blog' },
  { name: 'Categories', href: '/categories' },
  { name: 'Authors', href: '/authors' },
  { name: 'About', href: '/about' },
]

Blog categories

You can add, edit and remove categories from the blog using the CategoryDetail object of the config.ts file. Each category is defined by a name, a description and some images. Edit them accordingly to your needs:

export const CategoryDetail = [
  {
    category: 'business',
    coverImage: '/images/categories/5.png',
    socialImage: '/images/categories/5.png',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Et nemo nimium beatus est.'
  },
  /* More categories... */
]

Blog authors

You can add, edit and remove authors from the blog using the AuthorDetail object of the config.ts file. Each author has some information properties as well as a profile image. Add or remove authors accordingly to your needs:

export const AuthorDetail = [
  {
    name: 'Maya Piretti',
    description: 'UX Designer',
    contact: 'maya@cssninja.io',
    image: '/svg/avatars/small/2.svg',
    bio: 'Maya Piretti is a highly skilled User Experience (UX) designer with over 8 years of industry experience, Maya has a proven track record of success in designing successful mobile apps and websites.',
    location: 'Roma, IT',
    company: 'Freelance',
    social: [
      {
        name: 'LinkedIn',
        link: 'https://www.linkedin.com/company/cssninja/',
        icon: 'brandico:linkedin',
      },
      {
        name: 'Facebook',
        link: 'https://www.facebook.com/cssninjaStudio',
        icon: 'brandico:facebook',
      },
      {
        name: 'Twitter',
        link: 'https://twitter.com/cssninjaStudio',
        icon: 'brandico:twitter',
      },
    ],
  },
  /* More authors... */
]

You should also set the default author using the DefaultAuthor object if you need to.

Other variables

There are 3 more variables that you can configure:

• PAGE_SIZE: controls the number of posts to show per page
• GITHUB_EDIT_URL: points to your repository GitHub Url in case you are building a collaborative website
• COMMUNITY_INVITE_URL: Points to a community service like discord or any other communication platform URL you set

Managing content

Now that you've configured the theme and added your personal and organization info, including Site logo and social links, you should now be ready to start adding and managing your content. We won't delete anything from the theme for now. You'll be able to do this later (e.g remove/add authors, categories and posts). We will simply follow along and learn every step you need to perform to create new blog posts.

The content folder

All your site content is and has to be stored inside the src/content folder. The different content types are then classified into sub-folders, like src/content/blog or src/content/pages. Each one of these sub-folders represents an Astro v2 concept called a collection.

A content collection is any directory inside the reserved src/content project directory, such as src/content/newsletter and src/content/blog. Only content collections are allowed inside the src/content directory. This directory cannot be used for anything else.

A content entry is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (.md) or MDX (.mdx) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.

Configuring content

There is another config.ts file that resides inside the src/content folder.This is a special file that Astro will automatically load and use to configure your content collections. This files contain schemas, that define and describe your collections (e.g in our case blog and pages).

Schemas enforce consistent frontmatter within a collection. A schema guarantees that your frontmatter exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know. Learn more about Astro content collections and schemas by reading the official documentation.

Creating a new author

Open the config.ts file, and before the end of the AuthorDetail object, add a new entry for your author information:

export const AuthorDetail = [
  /* other authors */
  {
    name: 'Your name',
    description: 'Your description',
    contact: 'you@yourmail.com',
    image: '/images/authors/your-photo.png',,
    bio: 'Your personal bio',
    location: 'Your location',
    company: 'Your company',
    social: [
      {
        name: 'LinkedIn',
        link: 'https://www.linkedin.com/you',
        icon: 'brandico:linkedin',
      },
      {
        name: 'Facebook',
        link: 'https://www.facebook.com/you',
        icon: 'brandico:facebook',
      },
      {
        name: 'Twitter',
        link: 'https://twitter.com/you',
        icon: 'brandico:twitter',
      },
    ],
  },
]

You now exist as an author in Folio. You can reference yourself when creating a new post, but we'll get to that later.

Creating a new category

We are also going to need a new category for our new post. Open the config.ts file, and before the end of the CategoryDetail object, add a new entry for your category. Let's call it anything for the sake of the example:

export const CategoryDetail = [
  /* other categories */
  {
    category: 'anything',
    coverImage: '/images/categories/5.png',
    socialImage: '/images/categories/5.png',
    description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Et nemo nimium beatus est.'
  },
]

TIP

Make sure you always name your categories using lowecase characters, to avoid any problems at build time.

Keep one of the existing images for your category or add an image of your own inside the src/images/ or in the src/svg/ folder if it's a vector image and update the category images paths accordingly.

Creating a new Post

Now that we have a new author and a new category to use, we can now create our new blog post and see how things work. You'll quickly see that it is very simple. Before creating our new post, you will need to have some content ready, as well as an image that will serve as featured and sharing image for your blog post.

Let's create a new file inside our src/content/blog folder. You can name it whatever you want but let's follow the pattern that we already have here. Each blog post starts with the date, so let's start ours with a date as well. Create a new markdown file inside src/content/blog and name it 2023-02-06-creating-my-first-post-with-astro.md. You should now have a blank page.

We are first going to add our post metadata. We are going to use a special syntax at the top of the page to define our metadata. All metadata should be defined between the --- and --- markers.

---
title: Creating my first post with Astro
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Et nemo nimium beatus est; Idemne, quod iucunde? Duo Reges constructio interrete. At iamdecimum annum in spelunca iacet.
author: Your name
publishDate: 2023-02-06T00:00:00.000Z
featured: false
coverImage: /images/posts/17.png
socialImage: /images/posts/17.png
categories:
  - anything
---

According to our post model, you need at least to define this data to be able to display your blog post properly. Notice how the author property should match the author name that we defined previously, to be able to fetch it dynamically. Also notice that we are using the anything category that we defined earlier as well. Below the --- frontmatter markers, let's add some markdown content to our post:

---
title: Creating my first post with Astro
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Et nemo nimium beatus est; Idemne, quod iucunde? Duo Reges constructio interrete. At iamdecimum annum in spelunca iacet.
author: Your name
publishDate: 2023-02-06T00:00:00.000Z
featured: false
coverImage: /images/posts/17.png
socialImage: /images/posts/17.png
categories:
  - anything
---
## Introduction
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

## First article part
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

## Second article part
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

## Third article part
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

## Fourth article part
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo

## Conclusion
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed auctor, magna in bibendum malesuada, risus purus venenatis urna, vel fringilla velit nibh id velit. Sed vel dictum velit. Nam sit amet suscipit risus. Praesent laoreet ligula id justo placerat, sit amet laoreet ligula tincidunt. Sed laoreet, magna a faucibus gravida, risus magna fringilla ligula, eget dictum augue odio eu metus.

We can also add some tags to our post. Those are arbitrary and don't need to be set in a configuration file. You can literally put anything you want in the tags section of the post metadata. Tags will be then parsed by the theme site wide and generated in a dedicated page. Let's add a few tags:

---
title: Creating my first post with Astro
description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Et nemo nimium beatus est; Idemne, quod iucunde? Duo Reges constructio interrete. At iamdecimum annum in spelunca iacet.
author: Your name
publishDate: 2023-02-06T00:00:00.000Z
featured: false
coverImage: /images/posts/17.png
socialImage: /images/posts/17.png
categories:
  - anything
tags:
  - lifestyle
  - hobbies
  - health
---

That's it, our new blog post is ready to be displayed. You don't have to do anything else as slug urls are automatically generated for you at build time. Let's start the project to preview it. If you've followed the installation steps previously, run the following command in the terminal, from the root of your project:

pnpm dev

open your browser at http://localhost:3000/blog to see the blog. Click on our newly created blog post to preview it in your browser at the following url: http://localhost:3000/blog/2023-02-06-creating-my-first-post-with-astro.

If you are good with your updates, run the build:

pnpm build

That's about it, you don't need to know anything else to be able to create and manage your content. You now need to figure out how you want to host your blog and upload your dist folder to your hosting, or via a more sophisticated deployment service like Vercel or Netlify.