/wowchemy-widget-starter

Primary LanguageHTMLMIT LicenseMIT

Wowchemy Widget Starter Template

Looking to build and publish a Wowchemy widget that doesn’t exist yet?

Wowchemy makes it easy to create a beautiful website for free. Edit your site in Markdown, Jupyter, or RStudio, generate it with Hugo, and deploy with GitHub or Netlify. Customize anything on your site with widgets, themes, and language packs.

👉 Core Concepts

  • Each Wowchemy widget consists of an HTML file
  • You may use Go Templating and Bootstrap layouts to design the widget HTML

🧑‍🎨 Create a Widget

  1. Click the Use This Template button on GitHub
    1. Name your repository wowchemy-widget-<WIDGET-NAME> where <WIDGET-NAME> is an appropriate name for your widget
  2. Browse your new GitHub project, click the go.mod file, and then the ✏️ pencil button to edit it
    1. Replace the placeholder URL in go.mod with your new GitHub URL in the form module github.com/<USERNAME>/wowchemy-widget-<WIDGET-NAME> where <USERNAME> is your GitHub username and <WIDGET-NAME> is the name of the widget
    2. Scroll to the bottom and click Commit Changes to save
  3. Browse to the layouts/partials/widgets/ folder, click my-widget.html, and click the ✏️ pencil button to edit it
    1. Rename my-widget.html in the text box to a unique ID in the form github.<USERNAME>.<WIDGET-NAME>.html, again replacing <USERNAME> with your GitHub username and <WIDGET-NAME> with your widget name
    2. Scroll to the bottom and click Commit Changes to save
  4. Edit the HTML for your new widget
    • You may use Go Templating and Bootstrap layouts
    • You can access page and section (widget instance) variables using $page and $section, respectively
    • Check out the built-in widgets for inspiration

Example

Say your GitHub username is pikachu and you wish to create a widget named pokemon:

  1. We click Use This Template and enter wowchemy-widget-pokemon as the project name
  2. We replace the first line of go.mod with module github.com/pikachu/wowchemy-widget-pokemon
  3. We browse to the layouts/partials/widgets/ folder, and rename my-widget.html to github.pikachu.pokemon.html
  4. We customize the HTML in github.pikachu.pokemon.html
  5. We add the widget to our site and share the widget with the community following the guide below

🌈 Add the Widget to your Site

  1. Install the widget by referencing it in your config/_defaults/config.yaml: 
    module:
  imports:
    # Your widget's GitHub URL (replace <USERNAME> and <WIDGET-NAME> with your GitHub username and widget name)
    - path: github.com/<USERNAME>/wowchemy-widget-<WIDGET-NAME>
  2. Create an instance of your widget in home/, for example let's create home/my-widget.md: 
    ---
# Replace <USERNAME> and <WIDGET-NAME> with your GitHub username and widget name, respectively.
widget: 'github.<USERNAME>.<WIDGET-NAME>'

# This file represents a page section.
headless: true

# Order that this section appears on the page.
weight: 1

title: Hello
---

Welcome to my new widget!

📢 Share your widget

Add the wowchemy-hugo-extension tag to your widget's GitHub repository to help other users find it.

Share your widget with the community on Discord and Twitter.