vZome supports sharing designs using Github Pages. In addition to vZome itself, all you need is a free GitHub account, and a GitHub repository named vzome-sharing with a main branch.

Simple Setup

Before you can share any designs from vZome, you need to do a one-time setup in GitHub. Obviously, you have to first sign up for a GitHub account if you don’t have one.

  1. Sign in to your GitHub account
  2. If you don’t already have a vzome-sharing GitHub repo, fork this template repository in your account. (The “Fork” button is in the upper right of that repo page.) The repo is pre-configured for vZome sharing, and your fork should keep the name vzome-sharing. If you already had a vzome-sharing repo, don’t fork the template; instead, copy the _layouts/vzome.html, _config.yml, and index.md files to your own repo.
  3. Follow instructions to enable GitHub Pages for your repo. Within a few minutes you should see a green banner that provides a link to the website built from the repository.

Next, there is a little preparation you need to do in vZome itself, so it is authorized to upload files to your new GitHub repository.

  1. In your web browser, sign in to your GitHub account.
  2. Save any vZome design to your file system, thereby giving it a name.
  3. Click on the share icon in the upper right. vZome will connect to GitHub (assuming you are online), and return with an authorization code.
  4. Click on the “Copy code and authorize” button. Your default browser will launch, and will show you the device activation page. Paste the authorization code into the form, and click “Continue”.
  5. GitHub will now ask you to click one more button, authorizing the vZome application to upload files to your repository.
  6. vZome will automatically continue the sharing process you initiated; see below for further steps.

Now you have a GitHub authorization that should last you for a while. vZome actually stores the authorization code, so you won’t have to authorize again until the code expires some months later. (vZome will prompt you to reauthorize when it becomes necessary.)

Sharing Designs

In the upper right corner of the toolbar area in vZome you will find the share button. Sharing a design requires a file name, so the button will only be enabled when you have saved a design at least once. (vZome does NOT try to ensure that your latest changes are saved before you share!)

When you click on the share button, you will see a dialog message while the files are generated and uploaded to GitHub. In a few seconds the process should complete, and you’ll see a link to visit the folder in GitHub where the assets landed. If you click that link, your default web browser will open onto that folder in GitHub. (Occasionally GitHub may require you to sign in first, if your session had already expired.)

GitHub will display a list of several files, including a README.md, and below the list it will render the README.md as styled text. (This is standard behavior for GitHub whenever a folder contains such a file.) The README.md contains several links, but the first two are the most important: a link to your generated, custom web page for the shared design, and a link to edit the source Markdown file from which that page is generated.

The first link is the one that you can copy and share on social media or email. However, that link won’t work immediately, as explained below, so always try the link and wait for it to render a correct page before you copy it and share it.

It is very important to understand the distinction between the generated web page and the source file from which it is generated. Although you can view both as web pages in your web browser, the first one is meant to be shared and read by others, and the second one is meant only for you. It is like the distinction between a published book and the original book manuscript given to a publisher. And, just as a publisher takes some weeks or months to actually publish a book, GitHub Pages takes a few minutes to generate the custom web page.

Waiting for the Build

Whenever you make a change to your vzome-sharing repo, whether by sharing a design from vZome, or by performing some of the customizations described below, you will find yourself waiting for the site to be regenerated by GitHub Pages. It turns out you don’t have to wait “in the dark”; if you click on the “Actions” tab for your repository, you’ll see a list of “workflow runs”. The top one will be the last build, or the current ongoing build. You can wait for its icon to turn green, and know that the build is finished.

Sometimes, you may make a change that breaks the build, meaning that your site won’t get updated. If that happens, you’ll see a red icon at the top of the list of workflow runs. You can click on it and drill in to see the detailed build log from GitHub Pages and Jekyll, and find out exactly how you broke things.

For both of these purposes, it is a good idea to just keep a dedicated browser tab open on the Actions page, so you always know what’s happening.

Customizing the Generated Page

The second link in the README.md takes you right into edit mode for the source for your custom web page, which is a file in a different folder, with the suffix .md (for Markdown). I strongly recommend that you spend a few minute learning the basics of Markdown syntax. You might also need to check the documentation of the exact dialect that GitHub uses, if you have difficulties.

The raw .md file content will look something like this:

---
title: Sample vZome Share
image: https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.png
layout: vzome
---

{% comment %}
 - [***web page generated from this source***][post]
 - [data assets and more info][github]

[post]: https://vorth.github.io/vzome-sharing/2021/11/29/sample-vZome-share-08-01-41.html
[github]: https://github.com/vorth/vzome-sharing/tree/main/2021/11/29/08-01-41-sample-vZome-share/
{% endcomment %}

<vzome-viewer style="width: 100%; height: 65vh;"
       src="https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.vZome" >
  <img src="https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.png" />
</vzome-viewer>

For the moment, you can ignore everything above the endcomment tag. Immediately below it, and above the vzome-viewer element that actually displays your design, is the perfect place to write whatever you want to say about your design. The .md file will be interpreted as Markdown, so you can do some formatted content, but you can also simply type, without worrying about line breaks, text fill, or other formatting.

The .md source file is yours to change however you like, just like the rest of the files in your entire vzome-sharing repo. You can add images, links to other web sites (like YouTube)… whatever you like. You can add a few more vzome-viewer elements for other designs you have shared, to make a complete article about some topic. Run with it!

To make your page immediately engaging, try not to put too much text before the first vzome-viewer element. You want someone to see the design immediately, without scrolling, even if they are viewing on a phone. Two or three average sentences is fine.

Check out this example of a customized .md page source file. In particular, note the use of {{ page.description }}. There are some conventions and mechanisms in the .md file that you will want to understand before you change them; see below for a full explanation.

After you commit your changes to the .md file (or any other file in the repo), the website rebuild may take a few minutes, and there is a limit on how many times the website will be rebuilt within an hour, so make sure that your new or modified web page is available before you share its link on social media! If you share it before the rebuild is complete, the link will not get embedded as a preview – your social media post won’t show the title, description, and preview image.

Customizing Your Site

Your vzome-sharing repository creates an entire website, and there is no reason to limit yourself to just the plain blog index that you get from the template repo.

You can create blog posts and regular web pages very easily, and make the website your own. Add as many HTML or Markdown pages as you like. Best of all, those pages can show your vZome designs in the same repository, using the same vzome-viewer custom element used in the generated, design-specific pages.

Customizing the Default Theme

The template repo you started with is set up to use the minima Jekyll theme to style your pages. If you look at the sample page for that theme, you should notice a few elements that are not present on your own vzome-sharing landing page. You’ll see a customized site title, an “About” link, and some changes to the page footer. All of these are easy customizations to the minima theme. You can examine the source for that sample page, but that is also the source for the theme itself, so it is a bit confusing. (Note: the latest minima theme version is 3.0, but GitHub Pages is still using 2.5.)

A better example is my own vzome-sharing site, where I have incorporated the custom title, the “About” page, a vZome logo image above the posts list, and the footer enhancements, including social media links. You can compare with the source changes to _config.yml and the added about.md and index.md files. To understand the exact details of those changes, look at the README for the minima theme. As that document explains, you can even go further with customizing the minima theme, changing page layouts and creating new ones.

Switching to a Different Theme

There is no reason you need to stick with the minima theme. There are about a dozen themes supported by GitHub Pages, and you can see them in the theme chooser as described in the Quickstart page. If you just want to browse the theme chooser, simply close that tab without hitting the “Select theme” button.

The customization mechanisms may vary for different themes, so don’t be surprised if you need to make some changes to _config.yml, as well as possibly adding some other layouts or template files. (Note that many of the themes do not generate a post index on the home page; this is the reason that the template vzome-sharing repo uses the minima theme by default.)

GitHub Pages puts a lot of power in your hands, as we’ll see below, so you are limited only by your imagination!

How It Works

GitHub Pages is based on Jekyll, a static website generator. Jekyll is used successfully to generate a wide variety of websites, so there is a lot you can learn, but we’ll just cover the basics here, and how vZome sharing makes use of Jekyll.

When you enable GitHub Pages on a repository, that means that somewhere in the cloud a Jekyll server walks over your repo and generates a website, which is itself hosted in the cloud (on the <yourusername>.github.io domain). Jekyll will rebuild that website whenever you commit some change to your repository, including when vZome uploads a design to share.

When vZome uploads a design to GitHub, it creates a dated, timestamped folder like this in your vzome-sharing repository. In that folder, vZome uploads several files:

  • the .vZome design file itself
  • a .shapes.json 3D preview file, for fast rendering online
  • a .png thumbnail image, for embedding links in social media
  • a README.md that explains how to share your design and web page
  • an index.md for casual, ad hoc sharing without publishing an indexed blog post

This folder will be included in the full website generated by Jekyll, but only as file assets; your vzome-sharing repository has been specially configured so that Jekyll won’t generate any web page from the README.md file. Jekyll will generate a page from index.md, of course.

If you select the “publish blog post” checkbox while sharing from vZome, vZome also creates a new post like this, a specially-named Markdown file under the _posts folder in your repo. (It will create the _posts folder, too, so you don’t need to worry about that.) These files are treated specially by Jekyll, and converted into web pages corresponding to blog posts. If you’re using the same theme as the template vzome-sharing repository, all blog posts get indexed by date on the main landing page of the website.

Post Source (.md) Details

Metadata for Embedding

Each vZome-generated .md file starts with Jekyll front matter:

---
title: Sample vZome Share
image: https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.png
layout: vzome
---

The first two variables, title and image, are used by the jekyll-seo-tag plugin, which GitHub Pages apparently uses automatically. These variables inform metadata included in the heading of your generated web page. This metadata helps somewhat with search engine optimization (SEO), but, more importantly, it gets used by social media platforms to render a preview card for your page.

The third variable, layout: vzome, is very important for enabling the use of the vzome-viewer custom element in this web page, so you don’t want to remove it. If you learn about the vzome custom layout provided with the vzome-sharing repo template, and the supporting Jekyll mechanisms, you can potentially create your own layouts for different purposes.

You will find that your generated pages all have a generic description in the HTML metadata. It is a very good idea to actually customize that description for each page:

description:
  This is my cool model of some geometry.  I made it in vZome,
  and I'm very proud of it.

That variable definition must go in the front matter with the others, before the second --- separator. The indentation is very important; read about YAML, the syntax for front matter, if you’re curious.

The sample post source illustrates how you can also render the description as part of your page text, using {{ page.description }}. This is a Liquid expression, used to substitute variables by Jekyll.

After the front matter, you will see a Jekyll comment section:

{% comment %}
 - [***web page generated from this source***][post]
 - [data assets and more info][github]

[post]: https://vorth.github.io/vzome-sharing/2021/11/29/sample-vZome-share-08-01-41.html
[github]: https://github.com/vorth/vzome-sharing/tree/main/2021/11/29/08-01-41-sample-vZome-share/
{% endcomment %}

This section is there just to help you navigate from the source .md file to the other two important places: the actual generated web page, and the supporting assets folder. Jekyll will completely ignore this section, since it is marked as a comment, so none of it will appear in the final web page.

vzome-viewer Instance

This, of course, is the reason for the whole enterprise, a custom HTML element that renders an interactive 3D viewer for your vZome design:

<vzome-viewer style="width: 100%; height: 60vh;"
       src="https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.vZome" >
  <img src="https://vorth.github.io/vzome-sharing/2021/11/29/08-01-41-sample-vZome-share/sample-vZome-share.png" />
</vzome-viewer>

Note: that is all one custom vzome-viewer element, with start and end HTML tags, and a nested img element. The src attribute on the main element is the most important thing, here. It links to your vZome design file, uploaded into the associated assets folder.

Next, notice the style attribute. This must contain valid CSS for styling the viewer element. It is entirely optional, so you can remove it if you are OK with the default style of the viewer. Lots of things are possible, here, but you should experiment at least with different approaches to height and width. See this CSS tutorial to learn more.

Finally, notice there is an image tag nested inside the vzome-viewer custom element. This provides a “fall-back”, something to render on the page even when the Javascript definition of the vzome-viewer failed to load correctly, or when the user has Javascript disabled in their browser. You will also see the image flash on the generated page initially, as the Javascript is loading.

Remember: this file is all yours, and if you want to render two or more vZome designs, you’re free to add more vzome-viewer elements to reference other .vZome files in your repo. This is pretty easy now, for two reasons. First, every README.md for a shared design includes an HTML snippet for a figure containing a vzome-viewer pre-configured for that design. Hover over the upper right corner to see an icon for copying to the clipboard. Second, you can use the vZome Online GitHub Browser to browse through all of your shared designs; again there’s a button to copy an HTML snippet for each one. You can even browse other users’ designs.

The vzome-viewer web component will continue to evolve, gaining new features. Your generated web pages will pick up these enhancements automatically, giving your readers new capabilities for interacting with your designs. In some cases, we will add optional features that won’t be used unless you specifically opt in by setting some attribute on the vzome-viewer element. This document will be updated soon with a link to full documentation for the vzome-viewer web component.

Template vzome-sharing Repository Details

Coming soon.