Skip to content

Commit c06b830

Browse files
authored
Introduction of new Markdown section in Writing (#122)
* 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
1 parent 3dd6102 commit c06b830

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed

writing/index.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,85 @@ julia> using Pluto
259259
julia> Pluto.run()
260260
```
261261

262+
## Markdown
263+
264+
\tldr{Markdown is also a good fit for literate programming, and Quarto is an alternative to notebooks.}
265+
266+
[Markdown](https://www.markdownguide.org/) is a markup language used to add formatting elements to plaintext text files.
267+
268+
### Plain Text Markdown
269+
Plain text markdown files, which have the `.md` extension, are not used for interactive programming, meaning one cannot run code written in the file.
270+
As a result, plain text markdown files are usually rendered into a final product by other software.
271+
272+
This is an example of a plain text markdown file:
273+
274+
````markdown
275+
# Title
276+
277+
## Section Header
278+
279+
This is example text.
280+
281+
```julia
282+
println("hello world")
283+
```
284+
````
285+
286+
### Quarto
287+
288+
[Quarto](https://quarto.org/) "is an open-source scientific and technical publishing system."
289+
Quarto makes a plain text markdown file (`.md`) alternative called Quarto markdown file (`.qmd`).
290+
291+
Quarto markdown files like plain text markdown files also integrate with editors, such as VSCode.
292+
293+
\vscode{
294+
295+
Install the Quarto [extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) for a streamlined experience.
296+
297+
}
298+
299+
Unlike plain text markdown files, Quarto markdown files have executable code chunks.
300+
These code chunks provide a functionality similar to notebooks, thus Quarto markdown files are an alternative to notebooks.
301+
Additionally, Quarto markdown files give users additional control over output and styling via the YAML header at the top of the `.qmd` file.
302+
303+
As of Quarto version 1.5, users can choose from two Julia engines to execute code - a native Julia engine and IJulia.jl.
304+
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.
305+
For this reason it's recommended to start with the native Julia engine.
306+
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).
307+
308+
Below is an example of a Quarto markdown file.
309+
310+
````quarto
311+
---
312+
title: "My document"
313+
format:
314+
# renders a HTML document
315+
html:
316+
# table of contents
317+
toc: true
318+
execute:
319+
# makes code chunks invisible in the output
320+
# code output is still visible though
321+
echo: false
322+
# hides warnings in the output
323+
warning: false
324+
# native julia engine
325+
engine: julia
326+
---
327+
328+
# Title
329+
330+
## Section Header
331+
332+
Below is an executable code chunk.
333+
334+
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.
335+
336+
```{{julia}}
337+
println("hello world")
338+
```
339+
````
340+
262341
## Environments
263342

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

0 commit comments

Comments
 (0)