Skip to content

Latest commit

 

History

History
264 lines (186 loc) · 9.18 KB

README.md

File metadata and controls

264 lines (186 loc) · 9.18 KB
Raw

Astro CloudCannon Starter

A starting point for developers looking to build a website with Astro, using Bookshop components in CloudCannon.

Create your own copy, and start creating your own components to use in the CloudCannon CMS. Build components using .jsx or .astro files.

To try to cut down on setup time this starter template includes some commonly used features in CloudCannon.

This template is aimed at helping developers build sites quickly, rather than providing editors with a fully built editable site. If you are an editor looking for an already built template, have a look at CloudCannon's templates page.

See a demo version of this site.

Getting Started

To start using this template, go to the GitHub repository, and click Use this template to make your own copy.

Commands

All commands are run from the root of the project, from a terminal:

Command Action
npm install Installs dependencies
npm run dev Starts local dev server at localhost:4321
npm run build Build your production site to ./dist/
npm run astro ... Run CLI commands like astro add, astro check
npm run astro -- --help Get help using the Astro CLI

Local Development

  1. Clone the repository
  2. Run npm install
  3. Run npm start

Features

Bookshop

Bookshop is a component development workflow for static websites.

Build custom components that non-technical editors can use in a page building experience in CloudCannon.

Bookshop is already set up on this project, so that you can start building components straight away.

To add a new component:

  1. Create a new folder in src/components using the component name as the folder name.
  2. Create two files in this folder src/components/example-component/example-component.astro
---
interface Props {
  background_color: string;
  text_color: string;
}

const block = Astro.props;
---

<section style={`background-color: ${block.background_color}; color: ${block.text_color};`}>
  <div class="container">
    Replace me
  </div>
</section>

<style>
  .container {
    max-width: var(--pageContainer);
    margin: 0 auto;
    padding-inline: var(--pagePadding);
  }
</style>

src/components/example-component/example-component.bookshop.yml

# Metadata about this component, to be used in the CMS
spec:
  structures:
    - content_blocks
  label: Example Component
  description: A short description.
  icon: 'cottage'
  tags:
    - Example

# Defines the structure of this component, as well as the default values
blueprint:
  background_color: '#ffffff'
  text_color: '#000000'

# Overrides any fields in the blueprint when viewing this component in the component browser
preview:

# Any extra CloudCannon inputs configuration to apply to the blueprint
_inputs:

Blog & Documentation Pages

Blog section with tags and pagination included.

Documentation, blog and other text heavy sections should replicate how the blog section is implemented in this template.

The blog pages in this template use MDX to allow for snippets. Snippets allow you to use HTML components throughout your markdown text.

A common layout, with changing markdown content is favored for these kinds of text heavy pages, rather than using Bookshop components - which are defined and managed in your markdown pages frontmatter.

These text heavy pages will be edited in CloudCannon's content editor, rather than the visual editor used for building pages with Bookshop components.

Image Optimization

Astro <Image /> is used in the two placeholder components in this template. An Astro <Image /> will process an image in your src/assets/images folder, and output an optimized image, like below:

<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp  240w,
    /_astro/my_image.hash.webp  540w,
    /_astro/my_image.hash.webp  720w,
    /_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="A description of my image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async" />

This template also demonstrates how to set uploads paths on an input level, to allow for both processed and unprocessed images on one site.

On this template, by default, image inputs are opened at public/images, meaning they are unprocessed images.

Components that use the Astro <Image /> component are configured so the image source input opens at src/assets/images, which are images to be processed and optimized on build.

SEO Controls

SEO inputs come set up and configured to allow editors to control SEO on a page-by-page, and sitewide basis.

Tailwind CSS

Use Tailwind to add utility classes to your HTML, allowing you to style your components without leaving your HTML. This can be used in combination with normal CSS and SCSS styling, leaving you to add styles to your site however you want.

To remove Tailwind CSS:

  1. Remove the following packages from your package.json:
"dependencies": {
  "tailwindcss": "^3.3.3",
  "@astrojs/tailwind": "^5.0.0"
}
  1. Remove mentions of Tailwind from your astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [tailwind()],
});
  1. Delete your tailwind.config.mjs file.

Font Awesome Icons

A Font Awesome Icon free icon pack is included, without having to set up your own kit in Font Awesome.

To add more icons:

  1. Go to the Font Awesome icon list
  2. Pick a free icon
  3. Go to src/components/utility/icon.jsx
  4. Import the component from '@fortawesome/free-solid-svg-icons', '@fortawesome/free-regular-svg-icons', or '@fortawesome/free-brands-svg-icons', depending on which kind of icon it is. Tip: After entering 'fa' into one of the destructured objects, you should see an autocomplete dropdown list to help you with the correct syntax.
  5. Add another if statement following the format the other icons use.
  6. Add the name you just used in the conditional of the if statement to data/icons.json, which populates the icon dropdown list used for icons in the placeholder components.

To remove Font Awesome Icons:

  1. Remove the following packages from your package.json:
  "dependencies": {
  "@fortawesome/fontawesome-svg-core": "^6.5.2",
  "@fortawesome/free-brands-svg-icons": "^6.5.2",
  "@fortawesome/free-regular-svg-icons": "^6.5.2",
  "@fortawesome/free-solid-svg-icons": "^6.5.2",
  "@fortawesome/react-fontawesome": "^0.2.0"
  }
  1. Remove src/components/utility/icon.jsx
  2. Remove any imports of the icon
import Icon from '../utility/icon';
  1. Remove icons.json
  2. Remove any select inputs that were using the icon
icon:
  type: select
  options:
    values: data.icons
  1. Remove icons from your defined data in cloudcannon.config.yml
data_config:
  icons:
    path: data/icons.json

Data files

Demonstrates using data files to:

  • Populate select inputs in CloudCannon. This is powerful for allowing editors to make styling changes to the page, within a set design system populated by an editable data file.
  • Set sitewide values such as the overall site SEO settings.
  • Control header and footer data to allow editors control over navigation.

Schemas

Shows how to set up schemas in CloudCannon to allow for non-technical editors to create new pages, with preset frontmatter and content. Schemas can be define on a collection level, allowing your new blog pages to be different to your new landing pages. This allows for your text heavy blog/docs pages to be built and edited in the content editor, while your other pages can be built with Bookshop in the visual editor.

CloudCannon Config

A cloudcannon.config.yml file has been provided with some configuration that starts to show what can be done to configure the CMS.

The placeholder Bookshop components show how to configure your components to control inputs and previews in CloudCannon.

Markdown Styles

Markdown toolbar has all the options supported in the rich text editor, along with stylings to make them work. See the CloudCannon Docs for more information.

CSS Variables

Shows how to set global CSS variables in Astro, to set commonly used values like pagePadding, and pageContainer.

Extra work could be done to write a node fs script to write said values from a data file to the appropriate places in the code, which would then allow editors to control sitewide styles like page max-width and padding.