{"id":13902884,"url":"https://github.com/compiiile/compiiile","last_synced_at":"2025-04-06T12:08:43.125Z","repository":{"id":65324908,"uuid":"464669326","full_name":"compiiile/compiiile","owner":"compiiile","description":"The most convenient way to render a folder containing markdown files. Previewing and searching markdown files has never been that easy.","archived":false,"fork":false,"pushed_at":"2024-04-12T17:25:10.000Z","size":26717,"stargazers_count":141,"open_issues_count":1,"forks_count":11,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2024-05-01T21:32:23.303Z","etag":null,"topics":["cli","markdown","preview","reveal-js","slides","vite"],"latest_commit_sha":null,"homepage":"https://compiiile.me","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/compiiile.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"AlbanCrepel","ko_fi":"alban_crepel"}},"created_at":"2022-02-28T22:50:00.000Z","updated_at":"2024-04-26T12:42:03.000Z","dependencies_parsed_at":"2023-02-10T05:45:38.128Z","dependency_job_id":"94e8a5b4-e41a-4704-87c2-26c80d01a327","html_url":"https://github.com/compiiile/compiiile","commit_stats":null,"previous_names":["albancrepel/compiiile"],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compiiile%2Fcompiiile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compiiile%2Fcompiiile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compiiile%2Fcompiiile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compiiile%2Fcompiiile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/compiiile","download_url":"https://codeload.github.com/compiiile/compiiile/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","markdown","preview","reveal-js","slides","vite"],"created_at":"2024-08-06T22:01:28.922Z","updated_at":"2025-04-06T12:08:43.096Z","avatar_url":"https://github.com/compiiile.png","language":"Vue","funding_links":["https://github.com/sponsors/AlbanCrepel","https://ko-fi.com/alban_crepel"],"categories":["Vue","Markdown Building Blocks","cli"],"sub_categories":["Markdown to Website / Blog"],"readme":"# Compiiile\n\n\u003e Compiiile is the most convenient way to render a folder containing markdown files. Previewing and searching markdown\n\u003e files has never been that easy (it's really just a command away !) :sparkles:\n\n## Preview\n\n![Demo](https://i.imgur.com/nCZlWDE.gif)\n\n\u003e Check the live demo here: https://compiiile.me/\n\n## Purpose\n\nI document everything in markdown and have always been frustrated not having a simple tool to just **preview** a whole\nfolder, being able to **search** through it, make **slides** out of it, and get a **production-ready** build of all the\nfiles as a knowledge base. On\ntop of that, finding a tool with a sweet and simple UI is not that easy.\n\nThat's what Compiiile does. And it does it hassle-free !\n\n## Features\n\n- [x] 📦 **No config required, everything just works out of the box, without changing your files** (resolves images and\n      relative links (cross-references), print-ready rendering, :sunny: light and :first_quarter_moon_with_face: dark themes)\n- [x] 🌱 Available everywhere with static files deployment: just host it somewhere and access it in any browser on your\n      computer, phone or whatever you are using\n- [x] :link: Quick access to your files via the navbar and links to the previous and next file (with table of content\n      generation)\n- [x] :tv: Display some files as slides\n- [x] :mag: **Full-text quick search with content preview**\n- [x] :zap: Hot-reload content preview as you edit it\n- [x] :tada: Supports MDX files: add your own components to your documentation\n- [x] :bulb: Can serve as knowledge base, and handles symlinks to reuse content\n- [x] :wrench: Customizable by env variables or config file, it's up to you\n- [x] :star2: You get it, it simply does the job, period.\n\n### What Compiiile isn't\n\n- It's not a markdown editor, there are already plenty available, just choose the one that works best for you, even the\n  simplest text editor will do.\n- It's not like VuePress, VitePress, Docusaurus or Notion. Compiiile's goal is to stay simple and stupidly easy without\n  any configuration.\n\n\u003e The goal is to help people rely purely on a **language** (_markdown_), not on _any_ platform.\n\n## Installation\n\nYou can install Compiiile either globally or per-project:\n\n### Globally\n\nOpen a terminal and type one of these commands, whether using [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) depending on which package manager you are using:\n\n```bash\nyarn global add @compiiile/compiiile # install globally with yarn\n# or\nnpm install -g @compiiile/compiiile # install globally with npm\n```\n\n### Per-project\n\nOpen a terminal inside the folder containing your markdown files. Then, add Compiiile as a local command using yarn or\nnpm:\n\n```bash\nyarn add @compiiile/compiiile # install as a project dependency with yarn\n# or\nnpm install @compiiile/compiiile # install as a project dependency with npm\n```\n\n### Using Docker\n\nFirst, copy the `./Dockerfile` from this repo to your root folder.\n\nRun the following commands:\n\n```bash\ndocker build -t \u003ccustom-image-name\u003e .\ndocker run -p 8080:80 \u003ccustom-image-name\u003e\n```\n\n\u003e Replace `\u003ccustom-image-name\u003e` with the tag you want. You should get Compiiile running on http://localhost:8080.\n\n### Using docker compose (with dev server)\n\nFirst, copy the `./docker-compose.yaml` from this repo to your root folder.\n\nThen just run the following command:\n\n```bash\ndocker compose up\n```\n\n\u003e You should get Compiiile running on http://localhost:4321.\n\n## Quick start\n\nTo make yourself an idea and quickly get started using Compiiile, here are some commands that you can run in your\nterminal to get Compiiile running with a couple of markdown files as tests:\n\n```bash\nmkdir test-compiiile \u0026\u0026 cd test-compiiile # creating a new folder and go into this folder\nyarn global add @compiiile/compiiile # installing compiiile as global dependency using yarn\necho '# Test Compiiile\\n\\n\u003e Here is a blockquote for you\\n\\n## Your markdown awaits below' \u003e README.md # a first test file\necho '---\\nasSlides: true\\n---\\n\\n# Slide 1\\n\\n---\\n\\n# And this is slide 2' \u003e slides.md # a second test file as slides\ncompiiile --title=\"📚 Compiiile\" # running Compiiile for these 2 files\n```\n\nEt voilà, you should be able to preview your files in your browser :tada:.\n\n## Usage\n\nOnce installed, 3 commands are available to see your beautiful markdown files :eyes::\n\n- `compiiile dev`: creates a web server to check your markdown files (alias to only `compiiile`)\n- `compiiile build`: builds all the files for you to serve them production-ready\n- `compiiile preview`: preview your production-ready build\n\nYou can run the command you want in your terminal while being in the desired folder.\n\nTo use these commands inside a javascript project, you just have to add these commands to the `scripts` section of your\n`package.json` file like so:\n\n```json\n{\n\t\"scripts\": {\n\t\t\"dev\": \"compiiile dev\",\n\t\t\"build\": \"compiiile build\",\n\t\t\"preview\": \"compiiile preview\"\n\t}\n}\n```\n\nYou can run these scripts by running `yarn \u003cscript\u003e` or `npm run \u003cscript\u003e` in your terminal (replacing `\u003cscript\u003e`\nwith your script name).\n\nThe build command builds your files in a `.compiiile/dist` folder at the root of your current directory by default.\nYou can override this parameter (see below on how to use a custom configuration).\n\n## Write some markdown (Compiiile-specific parameters)\n\nThe goal of this project is to get it running **without changing any markdown files already written**.\nYet, there are some things to consider to configure some files:\n\n### Slides\n\nTo make a file usable as slides, you only have to add this parameter to the `frontmatter` of your markdown\nfile:\n\n```md\n---\nasSlides: true\n---\n```\n\nIf you are not acquainted with frontmatter, it's just some file-specific parameters that you can put at the very\nbeginning of your file to be processed (make sure to separate frontmatter values from your content with an empty line\nafter the last `---`).\n\nBy adding the frontmatter parameter, the page will directly open up as slides.\n\nTo separate your slides, just separate the content of your markdown with:\n\n```md\n---\n```\n\n\u003e There must be an empty line before and after the `---`\n\nYou can also make fragments within slides by using 2 hyphens:\n\n```md\n--\n```\n\n:star2: You can make your slides print-ready by adding the `print-pdf` query parameter to your page,\nlike: `https://compiiile.me/s/slides-preview?print-pdf`.\n\nOther frontmatter keys are handled:\n\n- `title`: set the title to be displayed in the navbar and for SEO\n- `description`: set the description for SEO\n- `textAlign`: possible values\n  are [CSS text-align values](https://developer.mozilla.org/en-US/docs/Web/CSS/text-align) (`left`, `center`, ...). This\n  changes the default text alignment in slides. The default value is `center`.\n- `ignore` : Boolean value (`true` or `false`) to ignore the current file and exclude it from Compiiile (the file is not ignored by default).\n- `hidden` : Boolean value (`true` or `false`) to hide the file from the navbar and siblings links (the file is not hidden by default).\n\n\u003e :bulb: You can override slides theme 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.\n\n### Routing\n\nThe home page of Compiiile (`/`) points to a `README.md` file located at the root of your folder, or fallbacks to an `index.md` file.\n\n## Custom configuration\n\nHere is the list of parameters that you can set to customize Compiiile (none are required):\n\n| Parameter              | Type       | Description                                                                                                          |\n|------------------------|------------|----------------------------------------------------------------------------------------------------------------------|\n| `title`                | `string`   | The title to display on the top-left of the User Interface                                                           |\n| `description`          | `string`   | The description that is rendered by default for the SEO                                                              |\n| `logo`                 | `string`   | The relative path of the logo to display in the TopBar and as favicon                                                |\n| `logoUrl`              | `string`   | The url to go to when clicking on the logo, defaults to the home page if not set                                     |\n| `dest`                 | `string`   | The folder in which to build files, defaults to `./.compiiile/dist`                                                  |\n| `siteUrl`              | `string`   | The url of the website in production (without trailing slash), used for the SEO tag `og:image`                       |\n| `astroConfig`          | `Object`   | Override [default Astro config](https://docs.astro.build/en/reference/configuration-reference/)                      |\n| `data`                 | `Object`   | An object with data to use in MDX files (check use case below)                                                       |\n| `theme`                | `string`   | The website theme, value can be : `auto` (default value: adapts to system preferences) \\| `light` \\| `dark`          |\n| `useAutoTitles`        | `Boolean`  | If set to `true`, use the first file heading as title to be displayed in the navbar and for SEO. Defaults to `false` |\n| `noIndex`              | `Boolean`  | If set to `true`, the `robots.txt` file will disallow all routes, preventing indexation. Defaults to `false`         |\n| `publicDir`            | `string`   | The folder name in which you can serve public files, defaults to `public`                                            |\n| `vite.server.fs.allow` | `string[]` | Add local paths to vite's server fs allow list                                                                       |\n| `printReady`           | `Boolean`  | Add a `/print` page to display a full ready-to-print content (uses `@compiiile/compiiile-print`)                     |\n| `css`                  | `string`   | A relative path to a custom CSS file to customize the style \u003cbr/\u003e:warning: Requires `compiiile-pro`                  |\n\nYou can use these parameters in 2 ways:\n\n### Script arguments\n\nConfig parameters can be passed by script arguments.\n\nFor example, if you want to change the title, just run Compiiile like so:\n\n```bash\ncompiiile dev --title=\"My knowledge base 📚\"\n```\n\n### Config file\n\nAnother way to set default config parameters is to set them in a dedicated file named `compiiile.config.js` in the\nroot of your folder.\n\nThis should export an object, like in this example that shows common use cases :\n\n```js\nexport default {\n\ttitle: \"Compiiile\",\n\tlogo: \"./my-logo.png\",\n\tdest: \"my-custom-build-folder\"\n}\n```\n\n\u003e ⚠️ You should bear in mind that script arguments have priority over config file parameters.\n\n\u003e :bulb: Compiiile uses [c12](https://github.com/unjs/c12) to load the config file, which allows to **extend config values** from other files. See the [dedicated c12 documentation](https://github.com/unjs/c12?tab=readme-ov-file#extending-configuration) for more information.\n\n## Public files\n\nIf you want some files to be public, just create a folder named `public` at the root of your Compiiile folder.\n\nFor example, if you want to link to a local PDF in your Markdown file, you can put your PDF in your local public directory, in `public/my-pdf.pdf`.\nThen, all you have to do is creating a link in Markdown with an absolute path like so :\n\n```markdown\n[Check the PDF](/my-pdf.pdf)\n```\n\n## Use MDX\n\nv2 of Compiiile allows you to use MDX files with Vue components.\n\n### Using components\n\nLet's say we have Vue a component `Test.vue` making an API request and listing results:\n\n```vue\n\u003ctemplate\u003e\n\t\u003cdiv\u003e\n\t\t\u003ch2\u003eRandom users fetched from an API:\u003c/h2\u003e\n\t\t\u003cul\u003e\n\t\t\t\u003cli v-for=\"user in users\"\u003e\n\t\t\t\t{{ user.name.first }} \u003cspan class=\"uppercase\"\u003e{{ user.name.last }}\u003c/span\u003e\n\t\t\t\u003c/li\u003e\n\t\t\u003c/ul\u003e\n\t\u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\n\texport default {\n\t\tname: \"Test\",\n\t\tdata() {\n\t\t\treturn {\n\t\t\t\tusers: []\n\t\t\t}\n\t\t},\n\t\tmethods: {\n\t\t\tasync loadUsers() {\n\t\t\t\tconst res = await fetch(\"https://randomuser.me/api/?results=10\")\n\t\t\t\tthis.users = (await res.json()).results\n\t\t\t}\n\t\t},\n\t\tasync mounted() {\n\t\t\tawait this.loadUsers()\n\t\t}\n\t}\n\u003c/script\u003e\n\n\u003cstyle scoped\u003e\n\t.uppercase {\n\t\ttext-transform: uppercase;\n\t}\n\u003c/style\u003e\n```\n\nYou can use it your MDX file like so:\n\n```mdx\nimport Test from \"./Test.vue\"\n\n\u003cTest client:load /\u003e\n```\n\nYou should\nuse [Astro's client directives](https://docs.astro.build/en/reference/directives-reference/#client-directives) to load\nyour component's script.\n\n### Use config data values\n\nTo use config values, you can access it by importing the `site` variable in your MDX file and then access the `data`\nkey:\n\n```mdx\nimport { site } from \"virtual:compiiile\"\n\n# {site.data.someProperty}\n```\n\n## Ignoring files and folders\n\nTo ignore a whole folder or some files matching a certain pattern, you can add a `.compiiileignore` at the root of the folder where you run Compiiile.\n\nThis file accepts glob patterns to ignore files. For example, if you want to ignore files containing the word `preview` and files starting with a number,\nyou can simply put these 2 lines in your `.compiiileignore`:\n\n```ignorelang\n*preview*\n[1-9]*\n```\n\n## Common issues\n\n- Make sure that the absolute path to the folder where you are running Compiiile doesn't contain any special character\n  as it could prevent the project initialization.\n\n## Special thanks\n\n- [Astro](https://github.com/withastro/astro) for enabling us developers to make lightweight websites\n- [fzf-for-js](https://github.com/ajitid/fzf-for-js) for the search feature\n- [reveal.js](https://revealjs.com/) for displaying markdown files as slides\n- [Vite](https://vitejs.dev/) for helping modern frontend developers keep their mental health sane :heart:\n\n## Contributing\n\nContributions are welcome after discussing the object of your contribution in the `Issues` pages (because the goal is to\nkeep this project really simple and straightforward).\n\nYou can read more about it and the roadmap in the [dedicated contributing guide](./CONTRIBUTING.md).\n\n## Official integrations \u0026 community projects\n\nYou can add features to Compiiile by using the following projects:\n\n- [compiiile-pro](https://compiiile.me/c/3-pro-installation): Enhance your Markdown files, add diagrams, mindmaps, admonitions, and ready-made components\n- [compiiile-print](https://github.com/compiiile/compiiile-print): Add a print ready page containing all your Markdown files\n\nHere is a list of projects related to Compiiile developed by the community:\n\n- [compiiile-actions-cloudflare-pages](https://github.com/marketplace/actions/compiiile-cloudflare-pages): A simple GitHub action to deploy a Compiiile site to CloudFlare pages\n\n## Support\n\nOpen-source is a wonderful thing, so please if you found this project useful or use it as a part of a commercial\nproject, **consider making a donation**.\nYou can do it either via [GitHub donations](https://github.com/sponsors/AlbanCrepel) or\nvia [my ko-fi page](https://ko-fi.com/alban_crepel) where you can make a one-time or monthly donation by PayPal or card.\nThis allows you to use Compiiile as a **pay-what-you-want** service if you are not part of a non-profit project. But if\nyou are **making any revenue** using this project or even use it as a trainer, **making a donation would be expected**.\nYou can always contact me for a custom use of this project and any licence issue.\n\nThank you :heart:\n\n## License\n\nThis project is licensed under the terms of the GNU General Public License v3.0.\n\nSee [LICENSE.md](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompiiile%2Fcompiiile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcompiiile%2Fcompiiile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompiiile%2Fcompiiile/lists"}