Skip to content

Commit 8d45911

Browse files
committed
writing: index: final draft of new Markdown section
1 parent 5244e00 commit 8d45911

File tree

1 file changed

+44
-11
lines changed

1 file changed

+44
-11
lines changed

writing/index.md

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -261,13 +261,14 @@ julia> Pluto.run()
261261

262262
## Markdown
263263

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

266-
[Markdown](https://www.markdownguide.org/) can be an alternative to writing code in notebooks (such as Jupyter), and is particularly useful when the file itself is not the final product, which is a key element of literate programming. Markdown is a markup language used to add formatting elements to plaintext text files, for example to bold text one would write `**bold words**`. Markdown is portable so it can be opened by any text editor, such as VSCode.
266+
[Markdown](https://www.markdownguide.org/) is a markup language used to add formatting elements to plaintext text files.
267+
For example, to bold text one encapsulates words with double asterisks: `**bold text**` -> **bold text**.
268+
Markdown files can be opened by any text editor, such as VSCode, and are particularly useful when the file itself is not the final product.
267269

268270
### Plain Text Markdown
269271
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-
Plain text markdown files are not an alternative to writing code in notebooks.
271272
Plain text markdown files are usually rendered into something else, such as but not limited to documents (e.g., PDF, Word), websites, presentations, and even books.
272273

273274
This is an example of a plain text markdown file:
@@ -286,22 +287,54 @@ println("hello world")
286287

287288
### Quarto
288289

289-
An alternative to `.md` markdown files are Quarto markdown files (`.qmd`).
290-
[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system.
290+
[Quarto](https://quarto.org/) "is an open-source scientific and technical publishing system."
291+
Quarto makes a plain text markdown file (`.md`) alternative called Quarto markdown file (`.qmd`).
291292

292-
Unlike plain text `.md` markdown files, Quarto markdown files offer several advantages.
293-
In regards to writing code, the primary advantage is executable code cells/ chunks.
294-
In this fashion, Quarto markdown files are an alternative to writing code in notebooks (such as Jupyter).
295-
Quarto markdown files can also be rendered into the aforementioned output formats.
296-
297-
If the above example of a plain text markdown file were instead a Quarto markdown file, then within the editor, VSCode for example, one would be able to execute the `println("hello world")` Julia code and view the output.
293+
Quarto markdown files like plain text markdown files also integrate with editors, such as VSCode, and can be rendered into various output formats, such as websites.
298294

299295
\vscode{
300296

301297
Install the Quarto extension for a streamlined experience.
302298

303299
}
304300

301+
Unlike plain text markdown files, Quarto markdown files have executable code chunks.
302+
These code chunks provide a functionality similar to notebooks, which makes Quarto markdown files an alternative to writing code in notebooks.
303+
Additionally, Quarto markdown files give users additional control over output and styling via YAML headers.
304+
305+
Below is a revised markdown example using Quarto.
306+
If this file were opened in an editor such as VSCode one could execute the `println("hello world")` Julia code and view the output.
307+
Also, notice the YAML header at the top of the page that defines the document's title and specifies to make the code chunks invisible via the `echo: false` command.
308+
When `echo` is set to `false` the output of the code chunks will be displayed but the code itself will be hidden.
309+
310+
Last, as of Quarto version 1.5, Julia programmers have the option to use a native Julia engine to execute code - previously IJulia.jl was the only Julia engine.
311+
The primary difference betweens IJulia.jl and the native Julia engine is that the native Julia engine does not depend on Python and can utilize local environments.
312+
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).
313+
To use the native Julia engine set `engine` equal to `julia` in the YAML header of the Quarto markdown file as seen below.
314+
315+
````quarto
316+
---
317+
title: "My document"
318+
format:
319+
html:
320+
toc: true
321+
execute:
322+
echo: false
323+
warning: false
324+
engine: julia
325+
---
326+
327+
# Title
328+
329+
## Section Header
330+
331+
Below is an executable code chunk.
332+
333+
```{{julia}}
334+
println("hello world")
335+
```
336+
````
337+
305338
## Environments
306339

307340
\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)