Qupid

Effortlessly build landing page for your product with declarative configuration and customizable sections. Qupid is made to prepare and build the landing page quickly.

🚀 Demo | 📚 Storybook | ⚡️ Stackbitz | 🐙 GitHub

***

Qupid is a React project that is constructed from your configuration definition where you describe what sections of the website you need and in which order. Then, your static website is being generated that you can publish.

***

All you need is to choose what sections do you need and specify the content like titles, subtitles, pictures in a single YAML configuration file like below.

site:
  title: Qupid
  description: >
    Effortlessly build landing page for your product
    with declarative configuration and customizable sections.
  favicon_url: /favicon.ico

sections:
  header:
    type: header
  hero:
    type: hero
  features:
    type: features
  footer:
    type: footer

📃 Table of contents

• ✅ Features
  • 🥇 Sections
  • 🥈 Built-in capabilities
• 🚀 How to Use
  • 🧰 Custom GitHub action
  • 🗂️ Create from template
• 🛠️ Configuration
  • 🕸️ Site block
    • 🔍 SEO settings
    • 📊 Analytics settings
  • 🧱 Sections block
  • 🎨 Theme block
  • ⚓ Section anchors
  • Ⓜ️ Markdown support
  • 🔣 Font Awesome support
  • 🖼️ Images and light/dark themes
  • 📝 Special characters in YAML
• 🤝 Feedback and Contributions
• 📃 License

✅ Features

🥇 Sections

Qupid comes with pre-built sections that you can use to create your landing page. You can choose which sections to include and in which order. Each section is customizable with various options.

Section	Description
Header	Top section with logo, title, navigation links, and theme switcher.
Footer	Bottom section with logo, description, icon links, and copyright text.
Hero	Prominent section with image, title, subtitle, and primary/secondary buttons.
Cards	Section with title, subtitle, and multiple cards (icons with title and description).
Steps	Section with title, subtitle, and multiple steps (numbered icons with title and description).
FAQ	Section with title, subtitle, and multiple questions with answers.
Terminal	Section with title, subtitle, and terminal-like code block with optional prompt.

Tip

See Storybook for live demo of each section and how to configure them or use Stackblitz to play with the configuration.

🥈 Built-in capabilities

• Responsive design
• Customizable themes (colors, fonts)
• Dark theme support
• Image inversion for light/dark mode
• Markdown support with code highlighting
• Font Awesome support
• SEO optimization with meta tags
• Open Graph tags for better social media sharing
• Analytics integration

🚀 How to Use

There are two main ways to use Qupid to generate your landing page. You can either use the custom GitHub action in your own repository or create a new repository from the template.

🧰 GitHub custom action

This option is suitable if you already have a repository for your project and want to add a landing page to it. Assuming you have a repository with some images already that can be used on the website, you can omit storing the Qupid source code in your repository. Instead, you can use the custom GitHub action that will build the website for you.

1. Enable GitHub Pages in your repository settings.

• Go to the "Settings" tab of your repository.
• Select "Pages" from the sidebar.
• Under "Source", select "GitHub Actions".

2. Create a new file .github/workflows/deploy-website.yml in your repository with the following example content.

Click to see example workflow content.

name: Deploy My Website

on: # Choose when to trigger the workflow on push or manual trigger
  push: # Trigger on push to main or master branch
    branches:
      - main
      - master
  workflow_dispatch: # Allow manual triggering of the workflow

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

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest

    steps:
      - name: Use Qupid
        uses: kungfux/qupid@main
        with:
          # Define your Qupid configuration here as a YAML string
          configuration: |+
            site:
              title: My Website
              description: This is my website built with Qupid.

            sections:
              header:
                type: header
                logo:
                  fa: fa fa-heart
                  invert_on: light
                title: My Website
                links:
                  home:
                    text: Home
                    href: '#hero'
                  features:
                    text: Features
                    href: '#features'
                  get_started:
                    text: Get Started
                    href: '#get_started'
                  faq:
                    text: FAQ
                    href: '#faq'

              hero:
                type: hero
                title: Welcome to My Website
                subtitle: The best place to showcase your product.
                image:
                  href: https://www.digitalsilk.com/wp-content/uploads/2020/06/website-development-process-hero-image.png
                  invert_on: light
                primary_button:
                  text: Get Started
                  href: #
                secondary_button:
                  text: Learn More
                  href: #

              features:
                type: cards
                title: What We Offer
                subtitle: Discover the amazing features of our product.
                cards:
                  - title: Easy to Use
                    description: Simple and intuitive interface for everyone.
                    icon: fas fa-thumbs-up
                  - title: Customizable
                    description: Tailor the product to fit your needs.
                    icon: fas fa-cogs
                  - title: Fast Performance
                    description: Optimized for speed and efficiency.
                    icon: fas fa-tachometer-alt
                  - title: Secure
                    description: Built with security in mind to protect your data.
                    icon: fas fa-shield-alt
                  - title: 24/7 Support
                    description: We're here to help whenever you need us.
                    icon: fas fa-headset
                  - title: Affordable
                    description: Great value for a powerful product.
                    icon: fas fa-dollar-sign

              get_started:
                type: steps
                title: Get Started
                subtitle: Follow these simple steps.
                steps:
                  - title: Sign Up
                    description: Create an account to get started.
                    icon: fas fa-user-plus
                  - title: Customize
                    description: Tailor the product to your preferences.
                    icon: fas fa-sliders-h
                  - title: Launch
                    description: Start using the product and enjoy its benefits.
                    icon: fas fa-rocket

              faq:
                type: faq
                title: Frequently Asked Questions
                subtitle: Got questions? We have answers.
                items:
                  - question: What is this product about?
                    answer: This product is designed to help you showcase your offerings effectively.
                  - question: How do I get started?
                    answer: Simply sign up, customize your settings, and launch!
                  - question: Is there customer support available?
                    answer: Yes, we offer 24/7 customer support to assist you.
                  - question: Can I customize the product?
                    answer: Absolutely! The product is highly customizable to fit your needs.
                  - question: What are the pricing options?
                    answer: We offer various pricing plans to suit different budgets.

              footer:
                type: footer
                logo:
                  fa: fa fa-heart
                  invert_on: light
                title: My Website
                description: The best place to showcase your product.
                copyright: © {year} My Website. All rights reserved.
                links:
                  email:
                    icon: fas fa-envelope
                    href: 'mailto:'
                  phone:
                    icon: fas fa-phone
                    href: 'tel:'
                  address:
                    icon: fas fa-map-marker-alt
                    href: #
                  twitter:
                    icon: fab fa-twitter
                    href: #

3. Commit and push the changes to your repository.
4. Enjoy your new landing page at https://<your-github-username>.github.io/<your-repository-name>/.

🗂️ Create from template

If you want to have a new separate repository for your landing page, you can use the Qupid template repository.

1. Click on the link to create a new repository from the Qupid template.
2. Name your repository and click "Create repository".
3. Enable GitHub Pages in your repository settings.

• Go to the "Settings" tab of your repository.
• Select "Pages" from the sidebar.
• Under "Source", select "GitHub Actions".

4. Modify the configuration.yaml file in the root of the repository to customize your landing page.
5. Commit and push the changes to your repository.
6. Enjoy your new landing page at https://<your-github-username>.github.io/<your-repository-name>/.

🛠️ Configuration

Configuring your landing page is done by YAML notation. If you are not familiar with YAML, you can Learn YAML in Y minutes.

Configuration that describes the structure and the content of the website to be generated should be defined in the configuration.yaml file in the root of the project (or in case of using the custom GitHub action, it can be defined directly in the workflow file as a multi-line string). There are 3 main configuration blocks: site, sections, and optinally theme.

🕸️ Site block

Site block is used to define site's title, favicon, base URL and SEO-related settings.

site:
  url: https://kungfux.github.io/qupid/
  base_url: /qupid
  title: Qupid
  favicon_url: /favicon.ico

Note

The base_url is required if your website is hosted in a subdirectory like https://<your-github-username>.github.io/<your-repository-name>/ to make sure all links and assets are correctly resolved. Omit it if your website is hosted in the root directory like https://<your-domain>/.

For GitHub Pages, both url and base_url are being set automatically by the custom GitHub action and the template repository workflow, so these settings can be omitted. In case you use custom domain, you have to set the url property accordingly and optionally base_url if needed.

🔍 SEO settings

SEO settings are optional but recommended to improve your website's visibility on search engines and social media platforms. Each SEO property generates corresponding meta tags in the HTML head section as well as Open Graph tags for better sharing on social media.

site:
  seo:
    description: Effortlessly build landing page for your product with declarative configuration and customizable sections.
    author: kungfux
    canonical_url: https://kungfux.github.io/qupid/
    image: https://kungfux.github.io/qupid/og-image.png
    keywords:
      - qupid
      - landing page generator
      - landing page builder
      - static site generator
      - static site builder
      - product website
      - github action
      - template repository

📊 Analytics settings

You can enable one or more analytics providers to track your website traffic. Just provide the required identifier for each provider you want to use.

site:
  analytics:
    google: G-XXXXXXXXXX # Google Analytics Measurement ID
    cloudflare: YOUR_TOKEN # Cloudflare Web Analytics token
    fathom: YOUR_SITE_ID # Fathom Analytics site ID
    goatcounter: yoursubdomain # GoatCounter subdomain (without https:// and .goatcounter.com)
    matomo: https://matomo.yourdomain.com/YOUR_SITE_ID # Matomo Analytics URL and site ID
    umami: https://umami.yourdomain.com/YOUR_WEBSITE_ID # Umami Analytics URL and website ID

🧱 Sections block

Use sections block to define which sections should display and in which order.

Each section has it's own configuration entries.Most of the elements are optional. Omit property declaration in the configuration if you don't need a section to display particular element.

sections:
  header:
    type: header
  hero:
    type: hero
  features:
    type: features
  footer:
    type: footer

Tip

See Storybook for live demo of each section and how to configure them or use Stackblitz to play with the configuration.

🎨 Theme block

Theme block can be used to override the default theme including colors and fonts.

theme:
  colors:
    background: 'oklch(1.0000 0 0)'
    foreground: 'oklch(0.1884 0.0128 248.5103)'
    ...
    font-sans: 'Open Sans, sans-serif'
    font-serif: 'Georgia, serif'
    font-mono: 'Menlo, monospace'
    dark:
      background: 'oklch(0 0 0)'
      foreground: 'oklch(0.9328 0.0025 228.7857)'
      ...
      font-sans: 'Open Sans, sans-serif'
      font-serif: 'Georgia, serif'
      font-mono: 'Menlo, monospace'

Tip

The easiest way to customize a theme is to use online tools like https://tweakcn.com/ or https://ui.shadcn.com/themes to generate all necessary keys and values.

⚓ Section anchors

Section to render is identified from the section type e.g. type: hero as in the example below while section key hero1 is converted into section's id that can be used in anchor links. Let's say you want to add a header links poiting to a section. Then, the configuration may looks like the following.

sections:
 header:
    type: header
    links:
      hero:
        text: Link to Hero Section
        href: '#hero1'
        tooltip: Go to Hero Section

  hero1:
    type: hero

Ⓜ️ Markdown support

Configuration settings under sections block that expect the text to display as a value (e.g. title, subtitle, description, copyright, question, answer), support markdown format. This is useful to make the text bold, or add a link instead of a text.

sections:
  faq:
    type: faq
    title: Frequently Asked Questions
    subtitle: '**Answers** to common questions.'
    items:
      - question: '*Can I use Markdown with Qupid?*'
        answer: >
          Yes! You can use Markdown for:
          - **Bold text**
          - _Italic text_
          - [Links](https://example.com)
          - `Inline code`
          - Lists and more

🔣 Font Awesome support

Image settings like image, logo, icon support Font Awesome.

sections:
  header:
    type: header
    logo:
      href: # Omit image path for Font Awesome icon
      fa: fas fa-rocket

🖼️ Images and light/dark themes

To make images adapt to light/dark themes, you can specify invert_on setting with either light or dark value. The image will be inverted when the specified theme is active.

sections:
  hero:
    type: hero
    image:
      href: /hero-light.png
      invert_on: dark

📝 Special characters in YAML

YAML has special characters that need to be escaped or enclosed in quotes to be interpreted correctly. This is especially important for GitHub custom action where the configuration is defined as a multi-line string in the workflow file.

Here are some common special characters and how to handle them:

• :, #, $, -, ,, {, }, [, ], &, *, %, |, > (special characters)

  Use quotes if they are part of a string value or escape them with a backslash. Example: title: "My Title: An Introduction" or title: My Title\: An Introduction.

• ", ' (double and single quotes)

  Use double or single quotes to enclose strings with special characters or spaces. Example: title: 'My "Special" Title' or title: "My 'Special' Title".

• \ (backslash)

  Use quotes if the backslash is part of a string value. Example: path: "C:\\Program Files\\MyApp".

• ` (backtick)

  Use quotes if the backtick is part of a string value. Example: code: "Here is some `inline code` in a sentence." or use backslash to escape it: code: Here is some \`inline code\` in a sentence..

🤝 Feedback and Contributions

Feel free to contribute by reporting issues, suggesting features, or submitting pull requests on the GitHub repository.

📃 License

The project is free to use and licensed under MIT License.

🔝 Back to top