QuickStart

Creating a website with Bestatic is pretty easy: Starting from scratch, you should see a working website in 5-10 minutes.

Install Bestatic

The installation is simple. If you need detailed instruction, please visit the Installation page.

• If you are using Microsoft Windows, just download the .exe file from here and double click to start installation. As long as you keep clicking Next or similar prompts (without chaning any default settings), it should get installed in a couple of minutes. You do not have to touch command line or play with environment variables.

• If you are using Linux, the exact installation process may depend on the distro that you are using.

  • If you are using Ubuntu or any other Ubuntu flavors, simply search the graphical software store/software center for bestatic and click install (type sudo password, if required). It should just install the Snap package.

  • While Snap is widely supported, in case your non-Ubuntu distro does not support it directly, you can use the command line to install snapd and then install bestatic. Distro-specific instructions are available here.

  • If Snap packages are not available to your disto for whatever reason, please see the instruction in the Linux Installation section for simple CLI installation of the Flatpak version of bestatic from the Flathub. If you install the Flatpak version, remember to add alias to follow the next steps.

• If you are using macOS, it is a bit tricky as Bestatic does not have a native mac package. Nevertheless, it can be installed via pip or pipx using homebrew. Click here for detailed instructions.

  
  
  

Create a website

After you installed bestatic, just do these simple steps:

• Open a terminal (Windows Powershell or Command Prompt for Windows; standard terminal emulator for Linux or macOS).

• Verify you have successfully installed bestatic and it is in PATH by typing the following.

1
2

bestatic version
# Bestatic version: 0.0.25

As long as you can see some output like "Bestatic version: 0.0.22", that means the installation is successful.

• Make a folder, go to it, and create a themes folder inside it using following:

1
2
3

mkdir mysite
cd mysite #replace cd with chdir for Command Prompt
mkdir themes

At this point, you just need to put a theme inside themes folder and a config.yaml file to generate the website.

• While you can choose any theme or even create your own using Jinja2 templating system, for now, just download or clone the bestatic GitHub repo and copy the Amazing folder from there to themes folder of your mysite folder.

• To create a config.yaml file and build the website, run the following command:

1

bestatic quickstart

This will ask to provide the title and description of the website like this:

Enter the title of the website:

Enter the description of the website:

As soon as you provide these information and press enter, you are good to go! In fact, bestatic already generated your website and blog in _output folder. If you have any server already installed in the system, this folder can be served from there. If not, no worries! The bestatic comes with its own server. Just type:

1

bestatic -s

and you can visit the your website live on http://localhost:8080. You can press Ctrl+C anytime to stop the bestatic server.

Add some content (optional)

While you already have a working website and a blog, it is probably a good idea to add some content now.

If you open your current folder in your file manager/file explorer, you will see, there are posts and pages directory. The posts folder should contain all your "blog"/"news" kind of content, whereas pages folder should contain all your static pages. As you can see bestatic quickstart already created two posts (the-first-article.md and the-second-article.md) and two pages (about.md and contact.md).

You can always copy and paste any of these pages (or posts) file to create another page or post with correct frontmatter format and then simply rename it to anything. But possibly a better way to create new content is using following command-line options.

To create a page:

1

bestatic newpage filepath

To create a post:

1

bestatic newpost filepath

A couple of things to remember here:

1. The .md extension will be added automatically to filename. You do not have to add it.

2. If only filename is passed for the filepath argument, new posts or pages will be created at ./pages or ./posts folder. If a specific path is mentioned in the filepath argument, the specific markdown files will be generated at that particular path and subdirectories will be automatically created.

For example, bestatic newpost sub/directory/test1 will create a new post file test1.md at ./posts/sub/directory location. Conversely, bestatic newpage testpage1 will create a new file testpage1.md ath the ./pages/ folder.

Now, all you need to do is to open these files in your favorite text editor/IDE (we recommend VS Code/Jetbrains ediotrs/Neovim) and fill it with your heart's content in markdown. If you already not familiar, markdown syntax is very easy to learn and you can complete the basics in 15 min. If you are an absolute beginner, we recommend MarkdownTutorial.com.

Edit the configuration (optional)

Bestatic is configurable via a yaml file config.yaml which should be present in the root directory of the website. You can change a bunch of things such as:

via this config file. Details are documented here.

Build the site and test it on local server

Whenever you have completed editing your files, just open the terminal and run:

1

bestatic -s

As we mentioned earlier, now your website can be viewed again on http://localhost:8080 using your favorite browser.

In fact, you can enable autoreload feature where bestatic will watch your files (including config.yaml file) and rebuild the website automatically whenever it detects a file change in the current directory. To do this, use:

1
2

bestatic -sa
# or bestatic --server --autoreload

Next steps

If you have completed building your website and tested well locally, just use a very simple command:

1

bestatic

This will generate the final version of your website and/or blog. You can now deploy the _output directory to any server of your choice; in fact, instead of building locally, you can use bestatic to build your site on the cloud (on GitHub pages/GitLab pages/Netlify/Cloudflare Pages/etc.) and deploy it automatically using a CI/CD system. These processes are actually very simple and fully documented here.

Thank you for trying out Bestatic!! You are very welcome to check the rest of the documentation. If you are having any issues, please come to talk with us at GitHub Discussions. Enjoy!!