Getting Started ==================== If you have successfully got StencilBox installed and running, then your first step is to try to build one of the sample build configs. Let’s spend a bit of time working out how everything fits together. ![png](_images/png-da536df4a71e4950f644bf72ee679149cb163940.png) * **Build Config** \- A build config is a YAML file that tells StencilBox how to build a page. It defines which template to use, where to save the build page, and which data files to use. * **Template** \- A template is an HTML file that defines the structure of the page. It uses Handlebars syntax to pull in data from the data files. * **Data Files** \- Data files are YAML files that contain the data that will be used to populate the template. They can contain any kind of data, and can be as simple or complex as you need. * **Built Page** \- The built page is the final output of the build process. It is an HTML file that can be viewed in a web browser. To get started, try building one of the sample build configs that come with StencilBox. You can find them by clicking on the "Build Configs" link, and then opening one of the sample build configs. Click the "**START BUILD**" button to start the build process. ![Starting a Build](_images/start-build.png) Once the build is complete, you should see a link to the built page. Click on the link to view the built page in your web browser. ![Build Complete](_images/build-complete.png) If you run into any issues, or have any questions, please refer to [Support](#support) for help. Open the built page in your browser, and you should see something like this; ![Built Page](_images/built-page.png) That’s a start, but now let’s edit the **Data File** to add your own links. You will need to open the data file on your file system, and to make this a little easier, StencilBox gives you the file path. ![Data File Path](_images/data-file-path.png) You can open the file in your favourite text editor (the screenshot below shows nvim), and for the cases of this tutorial, let’s add "creaturesinmyhead.com" to the list of links; ![Add Site](_images/add-site.png) Once eddited, let’s save the file, and then go back to StencilBox and re-run the build by clicking the "**START BUILD**" button again. If all has gone well, you should be able to refresh the page in your browser (or open it again if you closed it) and see your new link as follows; ![New Link Added](_images/homepage-new-link.png) That’s it for this quick start guide. You should now have a basic understanding of how StencilBox works, and how to create and edit build configs, templates, and data files. Next, you might want to explore [Creating Build Configs](buildconfigs/index.html) to learn how to create your own build configs from scratch. Alternatively, you can explore **Templates (Built-in)** in the navigation to learn about the built-in templates that come with StencilBox. StencilBox ==================== **Generate super speedy simple static sites, from sleek templates.** If you’ve ever used static site generators like Hugo, this is very similar. The emphesis of this is for the self hosted community. Think homepages of links, sidebars, etc. * [Installation Guide](install/docker-compose.html). * [Getting Started Guide](getting-started.html). This documentation site is llm.txt compatible. See [llm.txt](https://jamesread.github.io/StencilBox/llm.txt) and [llm-full.txt](https://jamesread.github.io/StencilBox/llm-full.txt). Support ==================== To get relatively quick access to help, **Discord** is where the chat community for StencilBox is. Note that this project is a free community open source project, and it relies on volenteers to spare their free time to help you. Please be patient and polite. ![inline](_images/icons/Discord.png) [Chat on Discord](https://discord.gg/jhYWWpNJ3v) If nobody is online, or you’re not getting the right level of support, you can raise a ticket with the project’s developers on GitHub. Again, please be patient and polite. ![inline](_images/icons/GitHub.png) [Open a support request on GitHub](https://github.com/jamesread/StencilBox/issues/new?assignees=&labels=support&template=support%5Frequest.md&title=) Build Configs ==================== A Build Config is a YAML file that tells StencilBox how to build a set of pages. Build Configs rely on a template to provide the basic structure of the page, and will often pull in data from data files. Here is an example of a build config; Build Config (`buildconfigs/homepage.yml`) ```yaml name: homepage outputdir: homepage template: links-homepage datafiles: links: data/sites.yml ``` You’ll see that this simple Build Config is just a few lines of YAML, and it pulls in a data file to populate the page. Here’s an example of the data file that goes with it; Data file (`buildconfigs/data/sites.yml`) ```yaml title: My Favorite Sites categories: - title: tech sites links: - url: github.com title: GitHub - url: slashdot.com title: Slashdot - url: stackoverflow.com title: Stack Overflow - title: Funny sites links: - url: xkcd.com title: XKCD - url: theonion.com title: The Onion ``` The data file is a list of objects, each with a name and url property. When the build is run, it looks up the template defined in the build config (links-homepage), and uses it to build the page. Once it’s all put together, it should show up in the SencilBox interface looking something like this; ![Build Config](../_images/homepage.png) The built page will be saved in the output directory defined in the build config (homepage in this case). You can open the "LINK" to see the built page; ![Built Page](../_images/homepage-built.png) The template used in this Build Config is [links-homepage](../builtin-templates/links-homepage.html). iframe Sidebar ==================== The iframe Sidebar template creates a simple sidebar with an iframe, to display multiple websites. The sidebar keeps the iframes loaded, so you can quickly switch between them. This is very useful for when you have a workflow that requires you to open the same set of websites repeatedly and you want to be able to quickly switch between them. There is also a simple "close" button to hide the sidebar when you don’t need it anymore. ![iframe Sidebar Built Page](../_images/iframe-sidebar.png) ## [](#%5Fdatafile%5Fstructure)Datafile structure buildconfigs/data/sites.yaml ```yaml links: - url: https://github.com title: GitHub icon: repos/dashboard-icons/png/github.png - url: https://gitlab.com title: GitLab icon: repos/dashboard-icons/png/gitlab.png - url: https://grafana.com title: Grafana icon: repos/dashboard-icons/png/grafana.png - url: https://prometheus.io title: Prometheus icon: repos/dashboard-icons/png/prometheus.png ``` You can see that the data file contains icons from a "dashboard-icons" repository. StencilBox can be setup to clone repositories at build time, and only include the files from that repository that you need. To do this you need to add a "repos" section to your build config. Here is an example build config that uses this template and data file. buildconfigs/iframe-sidebar.yaml ```yaml name: My sidebar of apps template: iframe-sidebar outputdir: sidebar repos: - url: https://github.com/homarr-labs/dashboard-icons.git timeout: 300 # approx 1.3gb, can take 5 minutes (300 seconds) to download datafiles: links: data/sidebar-links.yaml ``` The **dashboard-icons** repository contains a large number of icons for various web applications, but it’s almost 1.3Gb in size! Luckily, during build time, the "Vite" build tool that StencilBox uses will only include the files that are actually used in the final build, so the final output will be much, much smaller. Built-in Templates ==================== * [Links Homepage](links-homepage.html) * [IFrame Sidebar](iframe-sidebar.html) * [Status Page](status-page.html) Links Homepage (links-homepage) ==================== This template simply shows a page of links grouped by category. This might be useful for a homepage, or a page of links to your favorite sites. ![Built Page](../_images/homepage-built.png) ## [](#%5Fdatafile%5Fstructure)Datafile structure buildconfigs/data/sites.yaml ```yaml title: My Favorite Sites categories: - title: tech sites links: - url: github.com title: GitHub - url: slashdot.com title: Slashdot - url: stackoverflow.com title: Stack Overflow - url: https://grafana.example.com url_internal: http://grafana.internal:3000 title: Grafana - title: Funny sites links: - url: xkcd.com title: XKCD - url: theonion.com title: The Onion ``` Each link requires a `url` (used for the hyperlink) and `title`. Optional fields: * `url_internal` — when set, used as the base URL to fetch the favicon during build instead of `url`. Use this when the public URL sits behind a reverse proxy that requires authentication but an internal URL is reachable from the build environment. * `icon` — path or URL to a favicon; when set, automatic favicon fetching is skipped. ## [](#%5Fexample%5Fbuild%5Fconfig)Example Build Config Check out the [Build Configs](../buildconfigs/index.html) page for an example of how to use this template. Service Status page ==================== The service status page template is useful for quickly displaying the status of a number of services. This fits the StencilBox philosophy very well - a YAML data file is used to define the services and their status, and the template generates a simple, clean status page that can be hosted anywhere. StencilBox does not contain any functionality to automatically check the status of services, or update the data file. That is left up to you. ![Status Page Built Page](../_images/status-page.png) ## [](#%5Fdatafile%5Fstructure)Datafile structure buildconfigs/data/services.yaml ```yaml title: Service Status services: - name: Firewall status: good - name: Primary File Server status: good - name: Backup File Server status: critical - name: Web Server status: warning - name: Database Server status: good lastUpdated: 2024-10-01T12:00:00Z ``` ## [](#%5Fexample%5Fbuild%5Fconfig)Example Build Config buildconfigs/iframe-sidebar.yaml ```yaml name: Status page of Services outputdir: status template: status-page datafiles: status: data/services.yaml ``` The data file contains a title for the page, a list of services with their status, and a timestamp for when the status was last updated. The status can be one of; "good", "warning", "critical" or "unknown". Build URLs ==================== You can set `STENCILBOX_BUILD_URL_BASE` to specify the base URL for build URLs. This is useful if you are running Stencilbox behind a reverse proxy or in a different environment. Configuration ==================== All configuration of StencilBox is via a configuration file called `config.yaml`. When running StencilBox via Docker, this file is located in the `/config` directory. The configuration file can be created and edited using any text editor. The configuration file is in YAML format, which is a human-readable data serialization standard. The most basic `config.yaml` file cam be as simple as this: config.yaml ```yaml logLevel: info ``` | Option | Description | Default | Live Reloadable | Documentation | | ------------- | ----------------------------------------- | ------- | --------------- | -------------------------------- | | configVersion | The version of the configuration file. | 1 | No | \--- | | logLevel | The log level to use. | info | Yes | One of debug, info, warn, error. | | showFooter | Whether to show the footer in the web UI. | true | No | \--- | Installation via Docker Compose ==================== Using docker-compose is the recommended way to install StencilBox. This will ensure that you have a consistent and easy way to manage your StencilBox instance. Below is the `docker-compose.yml` file you can use to set up StencilBox. docker-compose.yml ```yaml --- services: stencilbox: container_name: StencilBox image: ghcr.io/jamesread/stencilbox:latest volumes: - stencilbox-config:/config restart: unless-stopped ports: - "4337:8080" volumes: stencilbox-config: name: stencilbox-config external: false ``` You should be able to save this `docker-compose.yml` file in a directory of your choice. Then you can start StencilBox with the following command: ```bash docker-compose up -d ``` This command will start the StencilBox service in detached mode. You can then access StencilBox by navigating to `` in your web browser. ## [](#%5Fnext%5Fsteps)Next steps If you see a web interface when you navigate to ``, then StencilBox is running successfully. You can now proceed to the [Getting Started Guide](../getting-started.html) to learn how to create your first static site with StencilBox. ## [](#%5Ftroubleshooting)Troubleshooting If you encounter any issues while running StencilBox, here are a few things to check: * Ensure that Docker and Docker Compose are installed and running on your machine. * Check the logs of the StencilBox container for any errors. You can do this with the command: ```asciidoc docker-compose logs stencilbox ``` * Get help from the community by visiting the [Support page](../support.html). Docker (standalone) ==================== Bash ```bash docker pull ghcr.io/jamesread/stencilbox:latest docker create \ --name StencilBox \ -v stencilbox-config:/config \ -p 4337:4337 \ --restart unless-stopped \ ghcr.io/jamesread/stencilbox:latest ``` Custom Repos ==================== StencilBox comes with a few built-in templates and a simple theme. However you may want to use a different theme, inject content into templates (via hooks), use custom icons, or even create your own templates. This is where custom repos come in. Custom repos are simply Git repositories that contain templates, assets, or other content that you want to use in your StencilBox builds. You can host these repositories anywhere - GitHub, GitLab, Bitbucket, or even a self-hosted Git server. To use a custom repo, you need to add it to your build config. See the build config below for an example: ```yaml name: My sidebar of apps template: iframe-sidebar outputdir: sidebar repos: - url: https://github.com/jamesread/StencilBox-custom-repo-example.git timeout: 60 # smaller repo, should be quick to download datafiles: links: data/sidebar-links.yaml ``` In the example above we’re adding a custom repo that contains a custom template and some hook files. When Built, the page looks like this - a green theme background, and a custom content block on the page too; ![Custom repo example](../_images/custom-repo-added.png) ## [](#%5Fusing%5Frepos%5Fduring%5Fbuilds)Using repos during builds When you add a repo in your build config, StencilBox will clone the repository to a temporary location during the build process. How these repos are used depends on the content; * If the repo contains `body.html` or `head.html` files, these are treated as "hooks" and will be injected directly into the template at the appropriate hook locations. These can contain any valid HTML (including `