Compiiile

Compiiile is the most convenient way to render a folder containing markdown files. Previewing and searching markdown files has never been that easy (it's really just a command away !) :sparkles:

Preview

Check the live demo here: https://compiiile.me/

Purpose

I document everything in markdown and have always been frustrated not having a simple tool to just preview a whole folder, being able to search through it, make slides out of it, and get a production-ready build of all the files as a knowledge base. On top of that, finding a tool with a sweet and simple UI is not that easy.

That's what Compiiile does. And it does it hassle-free !

Features

• [x] 📦 No config required, everything just works out of the box, without changing your files (resolves images and relative links (cross-references), print-ready rendering, :sunny: light and :first_quarter_moon_with_face: dark themes)
• [x] 🌱 Available everywhere with static files deployment: just host it somewhere and access it in any browser on your computer, phone or whatever you are using
• [x] :link: Quick access to your files via the navbar and links to the previous and next file (with table of content generation)
• [x] :tv: Display some files as slides
• [x] :mag: Full-text quick search with content preview
• [x] :zap: Hot-reload content preview as you edit it
• [x] :tada: Supports MDX files: add your own components to your documentation
• [x] :bulb: Can serve as knowledge base, and handles symlinks to reuse content
• [x] :wrench: Customizable by env variables or config file, it's up to you
• [x] :star2: You get it, it simply does the job, period.

What Compiiile isn't

• It's not a markdown editor, there are already plenty available, just choose the one that works best for you, even the simplest text editor will do.
• It's not like VuePress, VitePress, Docusaurus or Notion. Compiiile's goal is to stay simple and stupidly easy without any configuration.

The goal is to help people rely purely on a language (markdown), not on any platform.

Installation

You can install Compiiile either globally or per-project:

Globally

Open a terminal and type one of these commands, whether using npm or yarn depending on which package manager you are using:

yarn global add @compiiile/compiiile # install globally with yarn
# or
npm install -g @compiiile/compiiile # install globally with npm

Per-project

Open a terminal inside the folder containing your markdown files. Then, add Compiiile as a local command using yarn or npm:

yarn add @compiiile/compiiile # install as a project dependency with yarn
# or
npm install @compiiile/compiiile # install as a project dependency with npm

Using Docker

First, copy the ./Dockerfile from this repo to your root folder.

Run the following commands:

docker build -t <custom-image-name> .
docker run -p 8080:80 <custom-image-name>

Replace <custom-image-name> with the tag you want. You should get Compiiile running on http://localhost:8080.

Using docker compose (with dev server)

First, copy the ./docker-compose.yaml from this repo to your root folder.

Then just run the following command:

docker compose up

You should get Compiiile running on http://localhost:4321.

Quick start

To make yourself an idea and quickly get started using Compiiile, here are some commands that you can run in your terminal to get Compiiile running with a couple of markdown files as tests:

# creating a new folder and go into this folder
mkdir test-compiiile && cd test-compiiile
# installing compiiile as global dependency using npm
npm i -g @compiiile/compiiile
# a first test file
echo '# Test Compiiile\n\n> Here is a blockquote for you\n\n## Your markdown awaits below' > README.md
# a second test file as slides
echo '---\nasSlides: true\n---\n\n# Slide 1\n\n---\n\n# And this is slide 2' > slides.md
# running Compiiile for these 2 files
compiiile --title="📚 Compiiile"

Et voilà, you should be able to preview your files in your browser :tada:.

Usage

Once installed, 3 commands are available to see your beautiful markdown files :eyes::

• compiiile dev: creates a web server to check your markdown files (alias to only compiiile)
• compiiile build: builds all the files for you to serve them production-ready
• compiiile preview: preview your production-ready build

You can run the command you want in your terminal while being in the desired folder.

To use these commands inside a javascript project, you just have to add these commands to the scripts section of your package.json file like so:

{
	"scripts": {
		"dev": "compiiile dev",
		"build": "compiiile build",
		"preview": "compiiile preview"
	}
}

You can run these scripts by running yarn <script> or npm run <script> in your terminal (replacing <script> with your script name).

The build command builds your files in a .compiiile/dist folder at the root of your current directory by default. You can override this parameter (see below on how to use a custom configuration).

Write some markdown (Compiiile-specific parameters)

The goal of this project is to get it running without changing any markdown files already written. Yet, there are some things to consider to configure some files:

Slides

To make a file usable as slides, you only have to add this parameter to the frontmatter of your markdown file:

---
asSlides: true
---

If you are not acquainted with frontmatter, it's just some file-specific parameters that you can put at the very beginning of your file to be processed (make sure to separate frontmatter values from your content with an empty line after the last ---).

By adding the frontmatter parameter, the page will directly open up as slides.

To separate your slides, just separate the content of your markdown with:

---

There must be an empty line before and after the ---

You can also make fragments within slides by using 2 hyphens:

--

:star2: You can make your slides print-ready by adding the print-pdf query parameter to your page, like: https://compiiile.me/s/slides-preview?print-pdf.

Other frontmatter keys are handled:

• title: set the title to be displayed in the navbar and for SEO
• description: set the description for SEO
• textAlign: possible values are CSS text-align values (left, center, ...). This changes the default text alignment in slides. The default value is center.
• ignore : Boolean value (true or false) to ignore the current file and exclude it from Compiiile (the file is not ignored by default).
• hidden : Boolean value (true or false) to hide the file from the navbar and siblings links (the file is not hidden by default).

:bulb: You can override slides theme (light or dark) by passing it to a theme query parameter in your slide url (for example /s/slides?theme=light). See the theme config parameter below for valid values.

Routing

The home page of Compiiile (/) points to a README.md file located at the root of your folder, or fallbacks to an index.md file.

Custom configuration

Here is the list of parameters that you can set to customize Compiiile (none are required):

| Parameter | Type | Description | | ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | title | string | The title to display on the top-left of the User Interface | | description | string | The description that is rendered by default for the SEO | | logo | string | The relative path of the logo to display in the TopBar and as favicon | | logoUrl | string | The url to go to when clicking on the logo, defaults to the home page if not set | | dest | string | The folder in which to build files, defaults to ./.compiiile/dist | | siteUrl | string | The url of the website in production (without trailing slash), used for the SEO tag og:image | | astroConfig | Object | Override default Astro config | | data | Object | An object with data to use in MDX files (check use case below) | | theme | string | The website theme, value can be : auto (default value: adapts to system pr