From 5244e004d9658c4f014aa71615ba58cddbbf7cc3 Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Mon, 29 Jul 2024 17:13:31 -0500 Subject: [PATCH 1/6] writing: index: created a new section called Markdown with two sub-headers (plain text markdown and quarto) --- writing/index.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/writing/index.md b/writing/index.md index 03f5640..6f35ea2 100644 --- a/writing/index.md +++ b/writing/index.md @@ -259,6 +259,49 @@ julia> using Pluto julia> Pluto.run() ``` +## Markdown + +\tldr{Markdown is also a good fit for literate programming.} + +[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. + +### 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. +Plain text markdown files are not an alternative to writing code in notebooks. +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. + +This is an example of a plain text markdown file: + +````markdown +# Title + +## Section Header + +This is example text. + +```julia +println("hello world") +``` +```` + +### Quarto + +An alternative to `.md` markdown files are Quarto markdown files (`.qmd`). +[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system. + +Unlike plain text `.md` markdown files, Quarto markdown files offer several advantages. +In regards to writing code, the primary advantage is executable code cells/ chunks. +In this fashion, Quarto markdown files are an alternative to writing code in notebooks (such as Jupyter). +Quarto markdown files can also be rendered into the aforementioned output formats. + +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. + +\vscode{ + +Install the Quarto extension for a streamlined experience. + +} + ## Environments \tldr{Activate a local environment for each project with `]activate path`. Its details are stored in `Project.toml` and `Manifest.toml`.} From 8d4591138e67f4a0904791f4f77de105454b5a04 Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Tue, 30 Jul 2024 13:44:16 -0500 Subject: [PATCH 2/6] writing: index: final draft of new Markdown section --- writing/index.md | 55 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/writing/index.md b/writing/index.md index 6f35ea2..960afea 100644 --- a/writing/index.md +++ b/writing/index.md @@ -261,13 +261,14 @@ julia> Pluto.run() ## Markdown -\tldr{Markdown is also a good fit for literate programming.} +\tldr{Markdown is also a good fit for literate programming, and Quarto is an alternative to notebooks.} -[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. +[Markdown](https://www.markdownguide.org/) is a markup language used to add formatting elements to plaintext text files. +For example, to bold text one encapsulates words with double asterisks: `**bold text**` -> **bold text**. +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. ### 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. -Plain text markdown files are not an alternative to writing code in notebooks. 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. This is an example of a plain text markdown file: @@ -286,15 +287,10 @@ println("hello world") ### Quarto -An alternative to `.md` markdown files are Quarto markdown files (`.qmd`). -[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system. +[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`). -Unlike plain text `.md` markdown files, Quarto markdown files offer several advantages. -In regards to writing code, the primary advantage is executable code cells/ chunks. -In this fashion, Quarto markdown files are an alternative to writing code in notebooks (such as Jupyter). -Quarto markdown files can also be rendered into the aforementioned output formats. - -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. +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. \vscode{ @@ -302,6 +298,43 @@ Install the Quarto extension 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, which makes Quarto markdown files an alternative to writing code in notebooks. +Additionally, Quarto markdown files give users additional control over output and styling via YAML headers. + +Below is a revised markdown example using Quarto. +If this file were opened in an editor such as VSCode one could execute the `println("hello world")` Julia code and view the output. +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. +When `echo` is set to `false` the output of the code chunks will be displayed but the code itself will be hidden. + +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. +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. +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). +To use the native Julia engine set `engine` equal to `julia` in the YAML header of the Quarto markdown file as seen below. + +````quarto +--- +title: "My document" +format: + html: + toc: true +execute: + echo: false + warning: false +engine: julia +--- + +# Title + +## Section Header + +Below is an executable code chunk. + +```{{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`.} From 40acb74ba28091fbf9b865a54a47019b2e31599b Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Sun, 18 Aug 2024 13:40:15 -0500 Subject: [PATCH 3/6] writing: updated based on PR feedback --- writing/index.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/writing/index.md b/writing/index.md index 960afea..ff70c5a 100644 --- a/writing/index.md +++ b/writing/index.md @@ -264,12 +264,10 @@ julia> Pluto.run() \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. -For example, to bold text one encapsulates words with double asterisks: `**bold text**` -> **bold text**. -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. ### 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. -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. +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: @@ -290,37 +288,40 @@ println("hello world") [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, and can be rendered into various output formats, such as websites. +Quarto markdown files like plain text markdown files also integrate with editors, such as VSCode. \vscode{ -Install the Quarto extension for a streamlined experience. +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, which makes Quarto markdown files an alternative to writing code in notebooks. -Additionally, Quarto markdown files give users additional control over output and styling via YAML headers. +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. -Below is a revised markdown example using Quarto. -If this file were opened in an editor such as VSCode one could execute the `println("hello world")` Julia code and view the output. -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. -When `echo` is set to `false` the output of the code chunks will be displayed but the code itself will be hidden. - -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. -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. +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). -To use the native Julia engine set `engine` equal to `julia` in the YAML header of the Quarto markdown file as seen below. + +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 --- @@ -330,6 +331,8 @@ engine: julia 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") ``` From 66c25ca062c78aa2dafed2e29bd5d07fd2582e3f Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Thu, 29 Aug 2024 11:58:13 -0500 Subject: [PATCH 4/6] writing: markdown: quarto: fixed misspecified julia code chunk - previously {{julia}} but it should have been {julia} --- writing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/writing/index.md b/writing/index.md index ff70c5a..0c374ca 100644 --- a/writing/index.md +++ b/writing/index.md @@ -333,7 +333,7 @@ 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}} +```{julia} println("hello world") ``` ```` From e61dc6f9db44d46d7425789e4c74dec762268afd Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Thu, 29 Aug 2024 12:35:25 -0500 Subject: [PATCH 5/6] Sharing: Literate programming: created a new paragraph to discuss Quarto in more detail --- sharing/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/sharing/index.md b/sharing/index.md index cc8de3e..1ce5513 100644 --- a/sharing/index.md +++ b/sharing/index.md @@ -237,7 +237,12 @@ In another category, [Replay.jl](https://github.com/AtelierArith/Replay.jl) allo Scientific software is often hard to grasp, and the code alone may not be very enlightening. Whether it is for package documentation or to write papers and books, you might want to interleave code with texts, formulas, images and so on. In addition to the [Pluto.jl](https://github.com/fonsp/Pluto.jl) and [Jupyter](https://jupyter.org/) notebooks, take a look at [Literate.jl](https://github.com/fredrikekre/Literate.jl) to enrich your code with comments and translate it to various formats. -[Quarto](https://quarto.org/) is another cross-language notebook system that supports Python, R and Julia, while [Books.jl](https://github.com/JuliaBooks/Books.jl) is more relevant to draft long documents. +[Books.jl](https://github.com/JuliaBooks/Books.jl) is relevant to draft long documents. + +[Quarto](https://quarto.org/) is an open-source scientific and technical publishing system that supports Python, R and Julia. +Quarto can render markdown files (`.md`), Quarto markdown files (`.qmd`), and Jupyter Notebooks (`.ipynb`) into "documents (Word, PDF, presentations), web pages, blog posts, books, and more". +Additionally, Quarto makes it easy to share or [publish](https://quarto.org/docs/publishing/) rendered content to Github Pages, Netlify, Confluence, Hugging Face Spaces, among others. +[Quarto Pub](https://quartopub.com/) "is a free publishing service for content created with Quarto" and "is ideal for blogs, course or project websites, books, presentations, and personal hobby sites." ## Versions and registration From 3d804767ebe5a2b7c32329230308ec493835bd56 Mon Sep 17 00:00:00 2001 From: hail_hydra Date: Tue, 10 Sep 2024 09:23:33 -0500 Subject: [PATCH 6/6] sharing: updated literate programming quarto section based on PR feedback --- sharing/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sharing/index.md b/sharing/index.md index 1ce5513..cb1cef0 100644 --- a/sharing/index.md +++ b/sharing/index.md @@ -240,9 +240,9 @@ In addition to the [Pluto.jl](https://github.com/fonsp/Pluto.jl) and [Jupyter](h [Books.jl](https://github.com/JuliaBooks/Books.jl) is relevant to draft long documents. [Quarto](https://quarto.org/) is an open-source scientific and technical publishing system that supports Python, R and Julia. -Quarto can render markdown files (`.md`), Quarto markdown files (`.qmd`), and Jupyter Notebooks (`.ipynb`) into "documents (Word, PDF, presentations), web pages, blog posts, books, and more". +Quarto can render markdown files (`.md`), Quarto markdown files (`.qmd`), and Jupyter Notebooks (`.ipynb`) into documents (Word, PDF, presentations), web pages, blog posts, books, [and more](https://quarto.org/docs/output-formats/all-formats.html). Additionally, Quarto makes it easy to share or [publish](https://quarto.org/docs/publishing/) rendered content to Github Pages, Netlify, Confluence, Hugging Face Spaces, among others. -[Quarto Pub](https://quartopub.com/) "is a free publishing service for content created with Quarto" and "is ideal for blogs, course or project websites, books, presentations, and personal hobby sites." +[Quarto Pub](https://quartopub.com/) is a free publishing service for content created with Quarto. ## Versions and registration