Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduction of new Markdown section in Writing #122

Merged
merged 4 commits into from
Aug 26, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions writing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,85 @@ julia> using Pluto
julia> Pluto.run()
```

## Markdown

\tldr{Markdown is also a good fit for literate programming, and Quarto is an alternative to notebooks.}

[Markdown](https://www.markdownguide.org/) is a markup language used to add formatting elements to plaintext text files.

### Plain Text Markdown
Plain text markdown files, which have the `.md` extension, are not used for interactive programming, meaning one cannot run code written in the file.
As a result, plain text markdown files are usually rendered into a final product by other software.

This is an example of a plain text markdown file:

````markdown
# Title

## Section Header

This is example text.

```julia
println("hello world")
```
````

### Quarto

[Quarto](https://quarto.org/) "is an open-source scientific and technical publishing system."
Quarto makes a plain text markdown file (`.md`) alternative called Quarto markdown file (`.qmd`).

Quarto markdown files like plain text markdown files also integrate with editors, such as VSCode.

\vscode{

Install the Quarto [extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) for a streamlined experience.

}

Unlike plain text markdown files, Quarto markdown files have executable code chunks.
These code chunks provide a functionality similar to notebooks, thus Quarto markdown files are an alternative to notebooks.
Additionally, Quarto markdown files give users additional control over output and styling via the YAML header at the top of the `.qmd` file.

As of Quarto version 1.5, users can choose from two Julia engines to execute code - a native Julia engine and IJulia.jl.
The primary difference between the native Julia engine and IJulia.jl is that the native Julia engine does not depend on Python and can utilize local environments.
For this reason it's recommended to start with the native Julia engine.
Learn more about the native Julia engine in Quarto's [documentation](https://quarto.org/docs/blog/posts/2024-07-11-1.5-release/#native-julia-engine).

Below is an example of a Quarto markdown file.

````quarto
---
title: "My document"
format:
# renders a HTML document
html:
# table of contents
toc: true
execute:
# makes code chunks invisible in the output
# code output is still visible though
echo: false
# hides warnings in the output
warning: false
# native julia engine
engine: julia
---

# Title

## Section Header

Below is an executable code chunk.

If this file were opened in an editor such as VSCode one could execute the `println("hello world")` Julia code and view the output, like in a notebook.

```{{julia}}
println("hello world")
```
````

adrhill marked this conversation as resolved.
Show resolved Hide resolved
## Environments

\tldr{Activate a local environment for each project with `]activate path`. Its details are stored in `Project.toml` and `Manifest.toml`.}
Expand Down
Loading