Skip to content

Commit

Permalink
Introduction of new Markdown section in Writing (#122)
Browse files Browse the repository at this point in the history
* writing: index: created a new section called Markdown with two sub-headers (plain text markdown and quarto)

* writing: index: final draft of new Markdown section

* writing: updated based on PR feedback
  • Loading branch information
SaintRod authored Aug 26, 2024
1 parent 3dd6102 commit c06b830
Showing 1 changed file with 79 additions and 0 deletions.
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")
```
````

## Environments

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

0 comments on commit c06b830

Please sign in to comment.