> For the complete documentation index, see [llms.txt](https://quarkdown.com/wiki/llms.txt). # Quickstart Welcome to Quarkdown! This guide walks you through the main features you need to create your first document. > If you use VS Code, we strongly recommend installing the [official Quarkdown extension](https://marketplace.visualstudio.com/items?itemName=quarkdown.quarkdown-vscode). This guide provides a broad overview without diving deep into every detail. Each section includes links to other wiki pages where you can learn more about specific features. ## Creating a document > Reference: [Project Creator](cli-project-creator.md) To create a new document, run the project creator from your terminal: ```shell quarkdown create my-document ``` This command creates a new folder named `my-document`. If you want to use the current working directory instead, you can omit the name. For this quickstart, we recommend the following options: - Project name: `Quickstart` - Authors: \ - Document type: `plain` - Document language: `English` Once the project is created, open `my-document.qd` in your favorite text editor. You can delete the existing content inside the first section if you want to start fresh. ```diff ## Quickstart - Welcome to [Quarkdown](https://quarkdown.com)! - This is the starting point of your document. - ... ``` ### Choosing a document type > Reference: [Document types](document-types.md) During the initial setup, you choose a document type from one of the following options: - **`plain`**: A continuous flow layout similar to Notion or Obsidian, ideal for knowledge management and web viewing. - **`paged`**: A traditional document layout with page breaks, perfect for PDFs. - **`slides`**: A presentation format with interactive navigation. - **`docs`**: A documentation format with a sidebar and table of contents, ideal for knowledge bases and wikis. This wiki itself is a `docs` document. ### Choosing a theme > Reference: [Themes](themes.md) Themes are split into two groups: *color* themes define the color scheme of a document, while *layout* themes set the general structural rules of the layout. ```markdown .theme {paperwhite} layout:{latex} ``` Some popular combinations include: - `paperwhite + latex`: A clean academic look (this is the default) - `darko + minimal`: A dark theme with minimal styling - `galactic + hyperlegible`: The theme used in this wiki, with a highly readable font - `beaver + beamer`: An academic presentation style See [Themes](themes.md) for a complete list of available themes. ## Compiling > Reference: [Compiler](cli-compiler.md) Compile the document to make sure everything works as expected: ```shell cd my-document quarkdown c main.qd ``` You should see the HTML output inside the `output` directory. To export to PDF, add the `--pdf` flag: ```shell quarkdown c main.qd --pdf ``` See the [PDF export](pdf-export.md) page for more information about PDF export and its requirements. If you installed Quarkdown using a package manager or the install script, you should be ready to go. ## Live preview To launch live preview, append `-p` (preview) and `-w` (watch) to the compile command: ```shell quarkdown c main.qd -p -w ``` This opens the default browser automatically. To use a different browser, specify it with the `--browser` option, for example `--browser chrome`. If you use VS Code with the Quarkdown extension, you can launch the live preview by clicking the magnifying glass button or pressing `Ctrl/Cmd+Shift+V`. ## Markup Quarkdown builds upon Markdown and includes several GFM extensions. To try out basic markup, append the following to your document and experiment with it: ```markdown ### A Quarkdown tour No need to reinvent the wheel: you can make text **bold** or *italic*, ~~strike through~~, add `inline code`, create [links](https://quarkdown.com), and much more. - An unordered list - With multiple items 1. An ordered list 2. With multiple items ![Logo](image/logo.png) ``` Markup For a refresher on Markdown basics, see [markdownguide.org](https://www.markdownguide.org/basic-syntax). ### Image size > References: [Image size](image-size.md), [Size](sizes.md) You might have noticed that the image in the previous example appears too large. Quarkdown overcomes this well-known Markdown limitation by allowing you to specify image dimensions: ```markdown !(50%)[Logo](image/logo.png) ``` Now the image is sized appropriately. Image size This sets the image width to 50% of the available width while maintaining the aspect ratio. Supported units include `px`, `pt`, `cm`, `mm`, `in`, and `%`. If you omit the unit, Quarkdown assumes `px`. To specify both width and height: ```markdown !(6cm 2cm)[Logo](image/logo.png) ``` To specify only the height: ```markdown !(_ 2cm)[Logo](image/logo.png) ``` ### Figures > Reference: [Figures](figure.md) When an image stands alone, separated from other content, it automatically becomes a figure. Figures are centered and can have a caption. Take the previous image: ```markdown !(50%)[Logo](image/logo.png) ``` You can add a caption by appending a title in quotes: ```markdown !(50%)[Logo](image/logo.png "The Quarkdown logo") ``` Figure ### Equations and formulae > Reference: [TeX formulae](tex-formulae.md) You can include TeX equations using the `$ expression $` syntax. Note that whitespace matters. Add the following to the bottom of your document: ```markdown #### Equations $ E = mc^2 $ is Einstein's mass-energy equivalence formula. $ f(x, y) = \frac{x}{y} $ ``` Notice that the second equation appears centered on its own line, even though it uses the same syntax. Just like figures, isolated equations automatically become block equations. Equations ## Function call syntax > Reference: [Syntax of a function call](syntax-of-a-function-call.md) Before exploring more features, let’s look at Quarkdown’s function call syntax. Function calls start with a dot and use curly braces for arguments. Arguments can be positional or named: ```markdown .pow {5} to:{2} is a mathematical operation. ``` Function calls can be *inline* or *block*, depending on whether they appear within other content or stand alone. Block function calls also support an indented *block argument*, which always corresponds to the last parameter of the function: ```markdown .align {center} This multi-line paragraph is the block argument, and it's now centered in the document. ``` You can chain multiple function calls together, where the output of one becomes the first argument of the next: > **Example 1** > > ```markdown > .sqrt {10}::round::multiply {2} > ``` > > 6 > you can find a full list of available functions in the [documentation](https://quarkdown.com/docs/quarkdown-stdlib/). ### Variables > Reference: [Variables](variables.md) Define a variable using the `.var` function and access it like any other function: ```markdown .var {name} {John} My name is .name ``` To change a variable’s value, call it with a new argument: ```markdown .name {Jane} ``` ## Custom elements > Reference: [Declaring functions](declaring-functions.md), [Boxes](box.md) You can define custom functions using `.function`. Functions are reusable components that encapsulate logic and content. In this section, we create a function that generates an *Example* box, commonly used in educational documents. Start by defining a function without parameters: ```markdown .docauthors - ... .function {example} .box {Example} type:{tip} This is my example! ## Quickstart ... ``` Now call it: ```markdown ## Quickstart .example ... ``` Calling `.example` produces a nicely formatted box. Let’s enhance the function by adding a parameter for the box content. The syntax for parameters is `param1 param2 param3:`. ```markdown .function {example} content: .box {Example} type:{tip} .content ``` Update the call accordingly: ```markdown .example This is my example! ``` Custom element Congratulations! You’ve created your first reusable element using [boxes](box.md). Many more layout tools are available, such as [containers](container.md) and [stacks](stacks.md). For advanced styling of custom elements, you can use CSS rules. See [CSS](css.md) for more information. > For the sake of simplicity, let’s remove the function call for now: > > ```diff > - .example > - This is my example! > ``` ## Styling elements > Reference: [Element styling](element-styling.md), [Element styling properties](element-styling-properties.md), [Extending functions](extending-functions.md) You can alter the appearance and behavior of built-in Markdown elements, such as headings and paragraphs. Quarkdown provides a mechanism similar to Typst’s `#show` rules, based on the `.extend` function, to intercept and customize the primitive functions backing these elements. For example, to make all level 2 headings appear on a teal background: ```markdown .extend {heading} where:{depth: .depth::equals {2}} .super background:{teal} foreground:{white} ``` Every `## Heading` now renders with the new styling, while other levels remain unchanged. `.super` invokes the original function, optionally overriding any of its arguments. To add an icon to all external links, you can intercept the `.link` primitive function and add an [icon](icons.md) to its content: ```markdown .extend {link} where:{url: .url::startswith {https://quarkdown.com}::not} content: .super .content .icon {box-arrow-up-right} ``` To italicize the word “Quarkdown” in all paragraphs, you can use the [`.match`](regex-match.md) function: ```markdown .extend {paragraph} content: .super .content::match {Quarkdown} *.1* ``` In the previous snippet: - `content` is the intercepted argument from the `.paragraph` function; - `.content::match {Quarkdown}` finds the pattern “Quarkdown” in the paragraph content, and applies the transformation `*.1*` to it, which italicizes the matched text. `.1` is an [implicit lambda parameter](lambda.md); - `.super` is called with the modified content as its body argument. For more complex styling needs, you can use [CSS](css.md) rules via `.css` to target specific elements and apply custom styles, and `.cssproperties` to customize global properties. ## Numbering > Reference: [Numbering](numbering.md) Many documents, especially academic ones, require numbered elements such as sections, figures, tables, equations, and code. In Quarkdown, you can achieve this using the `.numbering` function. > Documents with the `paged` type come with default numbering enabled. Add a numbering scheme at the top of your document, right before the content begins: ```markdown .docauthors - ... .numbering - headings: 1.1.1 - figures: 1.1 .function {example} ... ## Quickstart ... ``` > This YAML-like syntax represents a [dictionary](dictionary.md) data type. Numbering Valid symbols for numbering formats are: - `1` for decimal numbers - `A` for uppercase letters - `a` for lowercase letters - `I` for uppercase Roman numerals - `i` for lowercase Roman numerals Any other character is treated as literal text. ## Table of contents > Reference: [Table of contents](table-of-contents.md) Longer documents often include a table of contents at the beginning that lists all sections and subsections. In Quarkdown, simply call the `.tableofcontents` function where you want the table of contents to appear: ```markdown .numbering - ... .tableofcontents ## Quickstart ... ``` ## Footnotes > Reference: [Footnotes](footnotes.md) Footnotes let you add additional information without cluttering the main text. Let’s add a footnote to our introduction: ```markdown ### A Quarkdown tour No need to reinvent the wheel: you can make text **bold** or *italic*, ~~strike through~~, add `inline code`, create [links](https://quarkdown.com), and much more[^1]. [^1]: All Markdown features are supported in Quarkdown ``` This is the GFM footnote syntax, which Quarkdown fully supports. Quarkdown also supports compact footnotes, which let you define a footnote inline, right where you reference it: ```markdown and much more[^: All Markdown features are supported in Quarkdown]. ``` In `plain` documents, footnotes appear in the margin next to the reference, similar to side notes. In `paged` and `slides` documents, footnotes appear at the bottom of the page or slide. ## Cross-references > Reference: [Cross-references](cross-references.md) Cross-references let you refer to numbered elements elsewhere in your document. First, add an ID to the target element. Then reference it using the `.ref {id}` function. Take our figure: ```markdown !(50%)[Logo](image/logo.png "The Quarkdown logo") ``` Add the `logo` ID to it and reference it in the text: ```markdown !(50%)[Logo](image/logo.png "The Quarkdown logo") {#logo} The Quarkdown logo is shown in .ref {logo}. ``` Cross-reference See [Cross-references](cross-references.md) to learn how to add IDs to other elements, such as sections, tables, equations, and code blocks. ## Page margins and counter > References: [Page format](page-format.md), [Page margin content](page-margin-content.md), [Page counter](page-counter.md) In `paged` and `slides` documents, you typically want a page counter to help readers navigate and understand where they are in the document. First, switch to the `paged` document type by changing the `.doctype` value at the top of your document: ```diff - .doctype {plain} + .doctype {paged} ``` > The default page format is A4. You can change it, along with other properties, using the `.pageformat` function: > > ```markdown > .pageformat {letter} margin:{2cm} > ``` Now add a page counter to the bottom center of each page: ```markdown .docauthors - ... .pagemargin {bottomcenter} .currentpage / .totalpages .numbering - ... ``` Each page now displays its number and the total number of pages. The `.pagemargin` function can add any kind of content to each page. See [Page margin content](page-margin-content.md) for all available margin positions. ### Persistent headings > Reference: [Persistent headings](persistent-headings.md) Page margins can also display the current section title on each page. The following example shows the current level-1 heading in the bottom left margin: ```markdown .pagemargin {bottomcenter} ... .pagemargin {bottomleft} .lastheading depth:{1} .numbering - ... ``` ## Multi-file projects > Reference: [Inclusion vs. subdocuments](inclusion-vs-subdocuments.md) There are two main ways to split a large document into multiple source files: inclusion and subdocuments. ### Including files > Reference: [Including other Quarkdown files](including-other-quarkdown-files.md) The `.include` function inserts the content of another Quarkdown file into the current one. This approach is common in LaTeX and other markup languages for splitting a large document into smaller, more manageable files, such as one per chapter or section. For our quickstart, we could split setup and content into two separate files: > my-document.qd ```diff - .docname {Quickstart} - .doctype {paged} - .doclang {English} - .theme {paperwhite} layout:{latex} - - .docauthors - - ... - - .pagemargin {bottomright} - .currentpage / .totalpages - - .pagemargin {bottomleft} - .lastheading depth:{1} - - .numbering - - headings: 1.1.1 - - figures: 1.1 - - .extend {heading} - ... + .include {setup.qd} + .include {content.qd} - .tableofcontents - - # Quickstart - - ... ``` > setup.qd ```markdown .docname {MyDocument} .doctype {paged} .doclang {English} .theme {paperwhite} layout:{latex} .docauthors - Quarkdown .pagemargin {bottomright} .currentpage / .totalpages .numbering - headings: 1.1.1 - figures: 1.1 .extend {heading} ... ``` > content.qd ```markdown .tableofcontents ## Quickstart ... ``` Here we used `.include` twice. For a larger number of files, consider using `.includeall` instead: ```markdown .includeall - setup.qd - content.qd ``` ### Referencing files > Reference: [Subdocuments](subdocuments.md) The second approach uses subdocuments, which are particularly common for knowledge bases and wikis. Subdocuments are independent units of content that share the same setup and configuration. You can reference them from other documents through links. > my-document.qd ```markdown - [Introduction](introduction.qd) - [Chapter 1](chapter1.qd) - [Chapter 2](chapter2.qd) - [Conclusion](conclusion.qd) ``` You can also visualize the knowledge graph formed by subdocuments: ```markdown .subdocumentgraph ``` Subdocuments ## Static assets > Reference: [HTML static assets](html-static-assets.md) When exporting to HTML, you might want to ship extra files alongside the generated document, such as a `robots.txt` or a `CNAME` for GitHub Pages. To do so, create a `public/` directory next to your main source file and place the files inside it: - my-document.qd - setup.qd - content.qd - public/ - robots.txt - CNAME Quarkdown copies everything inside `public/` to the root of the output directory as-is, without any processing. ## Conclusion Congratulations! You have completed the Quarkdown quickstart guide and are now familiar with its main features. You are ready to create your first real document. From here, you can explore more advanced topics in the rest of this wiki and in the [documentation](https://quarkdown.com/docs/quarkdown-stdlib/index.html).