How to create new posts or pages has already been described in quickstart. See more details here regarding commands bestatic newpage filepath and bestatic newpost filepath. You can always add the extra key: value pair in the front-matter section as described below.
All markdown file that Bestatic processes, need to have a yaml style frontmatter, i.e., key: value pairs (note the whitespace after key) need to be enclosed with three dashes --- in top and bottom. The title and description keys are required to be present in all markdown files. Do not enclose any of these values with quotation mark or anything else.
The slug key tells bestatic where to generate the webpage. For example, if ./pages/sub/directory/example1.md file has slug: slug1 set, this page will be generated and served at the /sub/directory/slug1 location.
Again, if ./posts/another/directory/example2.md file has slug: slug2 set, this page will be generated and served at the /posts/another/directory/slug2 location. If no slug key is present, that is fine; In that case, title will be slugified and pages will be served accordingly.
Enabling LaTeX formatting
Set the key: value katex: true, to make sure Bestatic themes will load katex.html.jinja in the page, and as a result all the LaTeX markups will be rendered correctly.
The blog posts can also have additional keys , such as date and tags. Currently, date in this format "March 12, 2024" are only accepted. The tags should be listed with comma (such as: markdown, css, html). If you want to use multi words tags, join them by hyphen, such as tags: tag1, this-one.
Custom page template
You do not have to use same page template throughout your site. You can potentially use a different design for each page!
While Bestatic by default uses page.html.jinja2 template to generate static pages and uses post.html.jinja2 to generate blog pages, these can easily be changed. Just use: template: custompage1.html.jinja2 in your blog's front matter and make sure your theme's template directory has custompage1.html.jinja2 template. Then you are good to go!
When you run bestatic quickstrt and add some static content, you will get a tree something like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
In the above filetree, lines # 2-44 delineate the files and folders from the _output directory which Bestatic generates (this folder can be served from any web server). And line # 45-92 list the files and folders that Bestatic used to generate the website.
In pre-existing files (line # 45-92):
There is a config.yaml file at line #45 (see details here).
There is a pages folder which contains markdown files for static/non-blog pages (line #46-48); note that, instead of this simple single directory as shown here, this can be nested and that organization will be maintained when Bestatic will generate the _output directory. Importantly, while writing in the _output directory, Bestatic will use the slug values to generate the pages (and not the filenames in pages folder).
There is a posts folder which contains markdown files for blog posts (line #49-51); note that, instead of this simple single directory as shown here, this can be nested and that organization will be maintained when Bestatic will generate the _output directory. Importantly, while writing in the _output directory, Bestatic will use the slug values to generate the blog pages (and not the filenames in posts folder).
There is a static-content folder (line # 52-54). When Bestatic builds site, this directory is directly copied to _output in a nested fashion.
Lines # 55-82 provide details of Amazing theme files. Details about themes are documented in a separate page.
Note: While it is not present here, but you can include a root-import directory which will be directly copied to the root of the generated site folder (in a nested fashion). This maybe helpful if you have to include some record in a particular folder for verification purposes (such as the .well-known directory).
In Bestatic generated files (_output directory; line # 2-44):
All the pages under pages folder before (as described above) are processed and resulted a folder here in _output directory with slug values as folder name (line # 2-5). Bestatic creates an index.html file in each of these slug folders so that URLs become pretty and pages (or posts) do not have a .html extension to its links. As mentioned before, nested directory structure in _pages_ and _posts_ would have resulted nested directory structure here as well.
All the pages under posts folder before (as described above) are processed and resulted in a folder inside _output/post folder, with slug values as the folder name, and an index.html file inside each of those slug folders (line # 23-26).
All blog posts are listed in posts page (line # 27-28; see pagination section below for more relevant details).
All the tags in the blogs have been processed to generate tags pages (which lists posts with a particular tag) in _output/post/tags (line # 10-26).
The static-content folder has been copied in a nested fashion, as expected (line # 42-44).
All the static content of the theme, such as CSS, JS, Images, etc., has been copied to _output/static folder (line # 30-41).
The index.html page in root of _output folder is the designated homepage (line #6). Also see details below for homepage customization.
Note that, Bestatic also generated line #7 index.json (search index, see below) and line #8 sitemap.xml (the XML sitemap, see below).
Bestatic, by default, assumes that you will be using a separate homepage template home.html.jinja2 where you are going to make the homepage in plain HTML. Default "Amazing" theme come with such a home.html.jinja2 template. However, this is not required and it is easy to change homepage type.
Custom static homepage
If you want to make a static page (such as your about page, contact page, etc.) your homepage, in that particular markdown file's front matter, put slug: index.html. This is a special slug and should be used for only one page in your entire website which you want to serve as your homepage.
Irrespective of location of that markdown file inside pages folder, this will be rendered as /index.html and will be served as homepage. Make sure homepage_type: default is set in the config.yaml file.
List of blog posts as homepage
If you want to put your (first of the) blog list pages as the homepage, put homepage_type: list in the config.yaml file and you are all set.
To learn how to control number of blog posts per list page see Paginating the Blog section below.
For your blog posts, Disqus and Giscus comments are supported out-of-the-box. But, you can actually use anythings else - as long as they provide a Javascript snippet that you can put under your post.html.jinja2 template (or whatever name you give to your blog post template).
If you are using Giscus or Disqus and provide the id under configuration file, Bestatic will make them available to your theme under variable name "giscus" and "disqus" respectively. If you are using theme that we provide, mentioning the id in configuration file will be sufficient for enabling comments.
To provide a Giscus id to Bestatic:
Make a GitHub repo, make it public, and enable discussion in that repo.
Install giscus app on that repo.
Use your repo id (such as GitHubUsername/repo) as the comment_system_id for Bestatic. See "comments" section under config file notes for details.
To provide a Disqus id to Bestatic:
Sign Up for Disqus and go to https://disqus.com/admin/create/.
Fill out the details, copy the shortname (As Disqus mentions: "Your unique disqus URL will be: shortname.disqus.com"), and click on Create site.
Use the disqus shortname as the comment_system_id for Bestatic. See "comments" section under config file notes for details.
Bestatic give you option to control the number of blog posts per list page via number_of_pages key in the config.yaml file. For example, if your have 24 blog posts and what to have 6 blog posts listed per page, put number_of_pages: 4 in the config.yaml file and Bestatic will generate /posts, /posts2, /posts3, and /posts4 pages automatically. If you have blog posts and do not specify this, Bestatic will list all posts in a single page (which will be served at /posts).
Bestatic, by default, assumes that you are creating a website and a blog. If your website does not have any blog/post/news like content (such as a standard academic profile website), that is perfectly fine. Just do not create any posts directory in your site's root directory. Also, if exists, you may want to remove number_of_pages, rss_feed, and comments keys from your config.yaml file.
Search functionality has been implemented in Bestatic using Fuse.js library which enables client-side fuzzy (approximate string matching) search. No action is required from user-end: Whenever the user adds new content and build the website, it automatically generates a new search index at /index.json. The search UI in the themes has been implemented by modifying a pre-existing Hugo UI.
Of note, with proper tweaking, any other client-side search protocols such as lunr.js, or pagefind, or even Algolia can be implemented. And of course, there is always Google Programmable Search Engine that can be implemented in any site.
Sitemaps are automatically generated by Bestatic using Python's ElementTree XML API. Make sure that siteURL parameter is currently supplied in config.yaml file so that Bestatic can list correct URLs. See config file section for details. The generated file is served at the /sitemap.xml.