/create-blox

🧑‍🎨 Create and publish your very own content blocks for Hugo

Primary LanguageHTMLMIT LicenseMIT

Wowchemy Block Starter Template

Looking to build and publish a Wowchemy Block 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 blocks, themes, and language packs.

👉 Core Concepts

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

🧑‍🎨 Create a Block

  1. Click the Use This Template button on GitHub
    1. Name your repository with an appropriate name for your block collection, such as alices-wowchemy-blocks
  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>/<COLLECTION-NAME> where <USERNAME> is your GitHub username and <COLLECTION-NAME> is a name for your collection of blocks
    2. Scroll to the bottom and click Commit Changes to save
  3. Browse to the blocks/ folder, click my-block.html, and click the ✏️ pencil button to edit it
    1. Rename my-block.html in the text box to a unique ID in the form github.<USERNAME>.<BLOCK-NAME>.html, again replacing <USERNAME> with your GitHub username and <BLOCK-NAME> with your block name. It's important to provide this globally unique block name, otherwise another block can conflict with your block.
    2. Repeat the above step to rename the style file, my-block.scss
    3. Scroll to the bottom and click Commit Changes to save
  4. Edit the HTML for your new block
    • You may use Go Templating and Bootstrap layouts
    • You can access page and block (page section) variables using $page and $block, respectively
    • Check out the built-in blocks for inspiration

Example

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

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

🌈 Add the Block to your Site

  1. Install the block by referencing it in your config/_defaults/config.yaml: 
    module:
  imports:
    # Your block's GitHub URL (replace <USERNAME> and <COLLECTION-NAME> with your GitHub username and block collection name)
    - path: github.com/<USERNAME>/wowchemy-block-<COLLECTION-NAME>
  2. Add the block to a page such as your homepage at content/_index.md: 
    ---
title: My page
type: landing

# Replace <USERNAME> and <BLOCK-NAME> with the GitHub username that published the block and the block name, respectively.
# For example, `github.com/pikachu/wowchemy-block-pokemon` would be referenced as `block: github.pikachu.pokemon`
sections:
  - block: 'github.<USERNAME>.<BLOCK-NAME>'
    content:
      title: My title
      text: Add any **markdown** formatted content here - text, images, videos, galleries - and even HTML code!
---

📢 Share your block

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

Share your block with the community on Discord and Twitter.