--- tags: docs --- # Marmite Command Line Interface Marmite CLI is designed to be always executed pointing to an `input_folder` where the markdown content is located, and besides generating the site it comes with other useful features. The basic usage is very simple: ```console $ marmite input_folder Site generated at input_folder/site ``` Or you can specify the output folder: ```console $ marmite input_folder output_folder Site generated at output_folder ``` > Check `marmite --help` for a complete list. Besides this basic usage Marmite comes with other useful arguments. ## Initialize a Project Marmite can gerate a site from any folder containing markdown files, however if you need to initialize a project from the scratch, marmite can generate the recommended structure. ```console $ marmite --init-site myblog Config file generated: "myblog/marmite.yaml" ``` The site will be created with the default configuration, it is possible to [[#Override Configuration]] passing each parameter e,g: `--name MySite`. The generated structure looks like: ```console $ tree myblog myblog ├── content │   ├── media/ │   ├── 2024-11-26-welcome.md │   ├── about.md │   ├── _404.md │   ├── _announce.md │   ├── _comments.md │   ├── _hero.md │   ├── _markdown_footer.md │   ├── _markdown_header.md │   ├── _references.md │   └── _sidebar.example.md ├── custom.css ├── custom.js └── marmite.yaml ``` Read more on [[Using Markdown to Customize Layout]] and [[Customizing Templates]] ## Add new content To add new content you just need to create new markdown files on the `content` folder, you can use your preferred tools and editors for that task. Marmite provides the utility to automate creating the file via CLI, which is useful to have the **date** attribute set automatically. ```console $ marmite myblog --new "My first post" -t "post,content" myblog/content/2024-11-26-12-34-27-my-first-post.md ``` Pass `-p` to create a page instead of a post. Pass `-e` to immediately open the file on the `$EDITOR` ## Generate the site ```console $ /marmite myblog -v Site generated at: myblog/site/ ``` Or specify a custom `output_folder`: ```console $ /marmite myblog /var/www/myblog -v Site generated at: /var/www/myblog ``` > It is possible to [[#Override Configuration]] during site generation, for example, passing `--pagination 5` to change how many posts to list per page. ### Rebuild when content changes Marmite can watch for changes on your project and rebuild the site automatically, it is required to inform the output folder for this functionality. Use `-w` or `--watch` ```console $ /marmite myblog /var/www/myblog -w Site generated at: /var/www/myblog Watching for changed on: myblog/ ``` ### Serving the site Marmite generates a flat site, which means you can open it directly on your browser (with some limitations) or use any web server to serve it. Marmite comes with a built-in server to use only locally. Use `--serve` to start the server. ```console $ /marmite myblog /var/www/myblog -w Site generated at: /var/www/myblog Watching for changed on: myblog/ Starting built-in HTTP server... Server started at http://0.0.0.0:8000/ - Type ^C to stop. ``` If you want to change the address use `--bind ip:port` > [!IMPORTANT] > The built-in server is not suitable for production, when deploying use a webserver such as [Nginx] or read the [[hosting]] guide to learn how to deploy to Github pages, Gitlab pages, Codeberg Pages, Netlify and more. ## Start a new theme **Marmite** comes with a default theme that is optimized for readabily on blogs, you can read more on [[Why to use marmite]] article. The built-n theme comes with various colorschemes and you can set the desired colorscheme on the `marmite.yaml` file or passing `--colorscheme` on the CLI. The built-in theme can be customized using the `custom.css` placed on your root folder, and individual templates can be overriden on a `templates/` folder. Read more on [[Customizing Templates]] However, if you want to start a new theme to fully customize you can use the `--start-theme` argument. ```console $ marmite myblog /tmp/mysite --start-theme Generated myblog/templates/* Generated myblog/static/* ``` Now you can freely edit the static files and templates. ## Generate configuration ### Default To generate default config file ```console $ marmite myblog --generate-config Config file generated: "myblog/marmite.yaml" ``` ### Override Configuration To override specific keys ```console $ marmite myblog --generate-config \ --name MySite \ --tagline "My articles" \ --pagination 20 \ --colorscheme gruvbox \ --url "https://myblog.com" Config file generated: "myblog/marmite.yaml" ``` ## CLI Help ```console $ marmite --help Marmite is the easiest static site generator. Usage: marmite [OPTIONS] [OUTPUT_FOLDER] Arguments: Input folder containing markdown files [OUTPUT_FOLDER] Output folder to generate the site [default: `input_folder/site`] Options: -v, --verbose... Verbosity level (0-4) [default: 0 warn] options: -v: info,-vv: debug,-vvv: trace,-vvvv: trace all -w, --watch Detect changes and rebuild the site automatically --serve Serve the site with a built-in HTTP server --bind Address to bind the server [default: 0.0.0.0:8000] -c, --config Path to custom configuration file [default: marmite.yaml] --init-templates Initialize templates in the project --start-theme Initialize a theme with templates and static assets --generate-config Generate the configuration file --init-site Init a new site with sample content and default configuration this will overwrite existing files usually you don't need to run this because Marmite can generate a site from any folder with markdown files --new Create a new post with the given title and open in the default editor -e Edit the file in the default editor -p Set the new content as a page -t Set the tags for the new content tags are comma separated --name Site name [default: "Home" or value from config file] --tagline Site tagline [default: empty or value from config file] --url Site url [default: empty or value from config file] --footer