Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kungfux/qupid

Effortlessly build your product website in minutes using declarative configuration and customizable sections. Deploy the website without storing the source code by using the provided custom action.
https://github.com/kungfux/qupid

website-generator website-template

Last synced: 6 months ago
JSON representation

Effortlessly build your product website in minutes using declarative configuration and customizable sections. Deploy the website without storing the source code by using the provided custom action.

Awesome Lists containing this project

README 

          






Qupid logo



# 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](https://kungfux.github.io/qupid/) | 📚 [Storybook](https://kungfux.github.io/qupid/storybook/) | ⚡️ [Stackbitz](https://stackblitz.com/github/kungfux/qupid?file=configuration.yaml) | 🐙 [GitHub](https://github.com/kungfux/qupid)



\*\*\*



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.






```yml

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](#-features)

  - 🥇 [Sections](#-sections)

  - 🥈 [Built-in capabilities](#-built-in-capabilities)

- 🚀 [How to Use](#-how-to-use)

  - 🧰 [Custom GitHub action](#-github-custom-action)

  - 🗂️ [Create from template](#️-create-from-template)

- 🛠️ [Configuration](#️-configuration)

  - 🕸️ [Site block](#️-site-block)

    - 🔍 [SEO settings](#-seo-settings)

    - 📊 [Analytics settings](#-analytics-settings)

  - 🧱 [Sections block](#-sections-block)

  - 🎨 [Theme block](#-theme-block)

  - ⚓ [Section anchors](#-section-anchors)

  - Ⓜ️ [Markdown support](#ⓜ️-markdown-support)

  - 🔣 [Font Awesome support](#-font-awesome-support)

  - 🖼️ [Images and light/dark themes](#️-images-and-lightdark-themes)

  - 📝 [Special characters in YAML](#-special-characters-in-yaml)

- 🤝 [Feedback and Contributions](#-feedback-and-contributions)

- 📃 [License](#-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](https://kungfux.github.io/qupid/storybook/) for live demo of each section and how to configure them or use [Stackblitz](https://stackblitz.com/github/kungfux/qupid?file=configuration.yaml) 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.



```yml

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://.github.io//`.



### 🗂️ Create from template



If you want to have a new separate repository for your landing page, you can use the [Qupid template repository](https://github.com/new?template_name=qupid&template_owner=kungfux).



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://.github.io//`.



## 🛠️ Configuration



Configuring your landing page is done by YAML notation. If you are not familiar with YAML, you can [Learn YAML in Y minutes](https://learnxinyminutes.com/yaml/).



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.



```yml

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://.github.io//` to make sure all links and assets are correctly resolved. Omit it if your website is hosted in the root directory like `https:///`.

>

> 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.



```yml

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.



```yml

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.



```yml

sections:

  header:

    type: header

  hero:

    type: hero

  features:

    type: features

  footer:

    type: footer

```



> [!TIP]

> See [Storybook](https://kungfux.github.io/qupid/storybook/) for live demo of each section and how to configure them or use [Stackblitz](https://stackblitz.com/github/kungfux/qupid?file=configuration.yaml) to play with the configuration.



### 🎨 Theme block



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



```yml

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.



```yml

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](https://www.markdownguide.org/) format. This is useful to make the text bold, or add a link instead of a text.



```yml

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](https://fontawesome.com/icons).



```yml

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.



```yml

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](https://github.com/kungfux/qupid).



## 📃 License



The project is free to use and licensed under [MIT License](LICENSE).



[🔝 Back to top](#top)