HAXcms requires being published in order to be visible to other people. Working locally or on Desktop or on a server, is akin to you writing a document on your computer. It's not shared with anyone. We recommend you setup publishing ahead of time to save hassle later.

Setting up publishing

From the HAXcms site listing page, click the settings gear in the top right corner.

Next you'll see a modal that has options for plugging in your github credentials. We don't save your password and this aspect is optional. If you do enter your password, a one time API call is made on your behalf from your container which will setup an ssh key pair. This allows for all future requests to publish to happen automatically on your behalf. Your password is not stored. If you don't want to set this part up, you can plug in the rest of the git settings, save, and then manually publish files after using the UI (see last heading on this page).


Publishing from your sites / new sites

When you want to share your site with people or update your website, hitting the Publish button inside of your site is how to do this. Click the settings gear in the bottom right to get started.

Select the settings gear under the additional menu options as an editor.

Currently GitHub is the only provider supported in the local installation method (or from DDEV / one of the supported container providers). In the future hitting publish will have additional development flexibility.

Edit site settings modal showing the Publish button.

Understanding what's actually happening

When you hit publish, a few things happen to make your site "web ready". This is the general order of those operations:

  1. HAXcms takes the underlying files and commits them all to version control (though they already should be)
  2. It then pushes these to the origin of the git repository (likely github)
  3. Then it switches to the branch you do your publishing from. In github, this is the gh-pages branch, but can deviate as needed.
  4. Next it deletes symlinks and replaces them with the correct references as needed and leverages the "cdn provider" you specified when setting up HAXcms in order to super charge your files for end users.
  5. It uses twig to step through and correctly rewrite references in the index.html of your site to match the paths of where it's going to be sent
  6. Then it adds all this to version control and sends it up to your gh-pages branch.
  7. It does some local file clean up and sets things back to master branch for the next time you go to work on everything

When this is all done, in the UI you'll see a link to your site after it's indicated a successful publish (meaning it pushed the files up there). Depending on where you host your content it may take a few minutes to see the change, though GitHub is usually up within about 2 minutes.

Once about 2 minutes or so has passed, refresh your live site address or type in the URL of the site. If you've been there previously, you'll probably see the same content / theme as the last time you were there. After about 5 seconds, a message will pop up indicating "new content available" and clicking it (or refreshing the browser) will give you your updated content.

This last step happens because of what's called a "service worker". This enables your site to be 100% offline capable and ensures that your site only uses traffic and data when it's absolutely necessary.

A note on non UI publishing workflows

You might not have (or want to) setup the credentials between HAXcms and github / your git repo. That's ok. After you hit publish go to terminal / a Git GUI and run the following to publish your site:

HAXcms will have made sure that the gh-pages and master branches are valid for distribution, even if it wasn't able to actually send these files to their publishing destination.