QuickStart

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

1. 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 (Assets section) 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. For more details and screenshots, please visit the Installation page.

• If you are using Linux, the exact installation process may depend on the distro that you are using.
  
  We recommend using Snap version or Flatpak version of bestatic for easy/graphical installation. For more details, please see below. For even more details and screenshots, please visit the Installation page.

  • 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). This will install the Snap version of bestatic.

  • If Snap packages are not available to your disto out-of-the-box or you prefer to use Flatpak over Snap, please similarly search the graphical software store/software center of your distro (for example, in case of Fedora/Mint/Pop!_OS/etc., Flatpak and Flathub are enabled by default) for bestatic and click install and accept any prompts.
    
    If you install the Flatpak version, remember to add alias to follow the tutorial's commands or replace all bestatic commands with flatpak run com.bestaticpy.bestatic commands for the rest of the tutorial.

  • If you prefer to stay away from these universal package formats, you can manually grab the tarball (x86-64 and ARM64/AArch64 tarball, as per your system's architecture), extract it, and run the install.sh script to install bestatic. For more details, please visit the Installation page.

• If you are using macOS, good news! As of version 0.0.36, Bestatic is now available as a native macOS package. You can download the .pkg installer file from here (grab the x86-64 or ARM64/AArch64 package, if you are using Intel or Apple Silicon, respectively) and double click to start installation. As long as you keep clicking Next or similar prompts (without changing any default settings), it should get installed in a couple of minutes.
  
  For more details (especially if you need to circumvent the Gatekeeper prompts regarding the security of the package), view screenshots, or learn more about alternate installation method via Homebrew/pipx, please visit the Installation page.

2. 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.36

As long as you can see some output like "Bestatic version: 0.0.36", 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 #this will create a new folder named "mysite"
cd mysite #replace cd with chdir for Command Prompt. This will change the current working directory to "mysite" folder.
mkdir themes #this will create a new folder named "themes" inside "mysite" folder.

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

• While you can choose any theme or even simply create your own using Jinja2 templating system, for now, just download the Amazing theme (a zip file) and unzip/extract the contents of it. Then copy the Amazing folder contents to the themes folder of your mysite folder. The hierarchy should look like this:

1
2
3
4
5
6

mysite/
├── themes/
│   └── Amazing/
│       ├── static/
│       ├── templates/
│       └── ...

• To create a bestatic.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.

3. 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.

4. Edit the configuration (optional)

Bestatic is configurable via a yaml file bestatic.yaml (previously config.yaml) which should be present in the root directory of the website. You can pretty much change everything about your website and blog using this config file. Some of the things you can change are:

Details are documented here.

5. 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 bestatic.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

You can also change the port number by using the -n or --portnumber flag. For example, bestatic -san 8081 will start the server on port 8081 (this feature is really handy when you are running multiple servers on the same machine).

For more details and other command line options, please visit the Command Line Options page.

6. 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!!