You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Copy file name to clipboardExpand all lines: writing/index.md
+79Lines changed: 79 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -259,6 +259,85 @@ julia> using Pluto
259
259
julia> Pluto.run()
260
260
```
261
261
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
+
262
341
## Environments
263
342
264
343
\tldr{Activate a local environment for each project with `]activate path`. Its details are stored in `Project.toml` and `Manifest.toml`.}
0 commit comments