# Literate programming workflow with ordinary jl scripts

**URL:** <https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598>\
**Category:** General Usage\
**Tags:** documentation\
**Created:** [October 5, 2023, 12:25am UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598 "2023-10-05T00:25:05Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![martin.d.maas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/martin.d.maas/32/50964_2.png) [@martin.d.maas](https://discourse.julialang.org/u/martin.d.maas)\
**Post date:** [October 5, 2023, 12:25am UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/1 "2023-10-05T00:25:05Z")

</div>

I am trying to do some literate programming.

The workflow I want to pursue is writing valid Julia code in a script that I can execute with VSCode to see the results, add markdown content in comments, and then produce some output file, ideally in markdown I can later post-process.

EDIT 1: I ended up answering my own initial question… I was struggling with multiline comments, and was using docstrings (“”" “”") instead… multilinecomments (#= =#) for the win. It seems that docstrings are part of the code, and that literate programming is done with comments only.

EDIT 2: However, I’m still facing some issues. I don’t know how to capture output with Literate.jl, and I’m still struggling with multiline comments in Weave.jl, so I don’t know which is the best tool. Maybe use Literate + Weave, or Literate + Documenter?

Anyway, if anyone is doing literate programming and wants to share tips or their favourite workflow, I would be glad to hear.

---

<div class="post-metadata">

**Author:** ![lostella](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lostella/32/356_2.png) [@lostella](https://discourse.julialang.org/u/lostella)\
**Post date:** [October 5, 2023, 5:48pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/2 "2023-10-05T17:48:54Z")

</div>

[Pluto notebooks](https://github.com/fonsp/Pluto.jl/blob/main/sample/Basic.jl) are just Julia scripts with markdown strings interleaving code blocks. Would that not work?

---

<div class="post-metadata">

**Author:** ![martin.d.maas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/martin.d.maas/32/50964_2.png) [@martin.d.maas](https://discourse.julialang.org/u/martin.d.maas)\
**Post date:** [October 5, 2023, 5:58pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/3 "2023-10-05T17:58:38Z")

</div>

I think the input of Pluto notebooks are small code blocks, and the output is a regular .jl script. I’m looking for something where the input is a .jl script and the output is a document.

---

<div class="post-metadata">

**Author:** ![martin.d.maas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/martin.d.maas/32/50964_2.png) [@martin.d.maas](https://discourse.julialang.org/u/martin.d.maas)\
**Post date:** [October 5, 2023, 6:15pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/4 "2023-10-05T18:15:40Z")

</div>

Ok, it turns out that Literate.jl can capture output as well…

```julia
Literate.markdown("test.jl", execute=true, documenter=false, credit=false)

```

This command generates some very general-purpose markdown, and is really close to what I was looking for.

---

<div class="post-metadata">

**Author:** ![rdavis120](https://avatars.discourse-cdn.com/v4/letter/r/b5a626/32.png) [@rdavis120](https://discourse.julialang.org/u/rdavis120)\
**Post date:** [October 5, 2023, 8:06pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/5 "2023-10-05T20:06:42Z")

</div>

You might want to try to use [Quarto](https://quarto.org) It will have a separate vscode extension.

---

<div class="post-metadata">

**Author:** ![martin.d.maas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/martin.d.maas/32/50964_2.png) [@martin.d.maas](https://discourse.julialang.org/u/martin.d.maas)\
**Post date:** [October 5, 2023, 8:46pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/6 "2023-10-05T20:46:06Z")

</div>

I’ll check out their vscode integration, but it looks like the workflow starts with markdown + placing code within code fences. So, at first this will collide with the VS code REPL integration…

I think I almost got it with Literate (+ probaby CommonMark.jl)… but maybe I’m insisting on the wrong approach of starting with a regular julia script, and literate programming just tends to gravitate a lot towards notebooks these days.

---

<div class="post-metadata">

**Author:** ![Kirby\_Zhang](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kirby_zhang/32/36204_2.png) [@Kirby\_Zhang](https://discourse.julialang.org/u/Kirby_Zhang)\
**Post date:** [March 25, 2025, 2:58pm UTC](https://discourse.julialang.org/t/literate-programming-workflow-with-ordinary-jl-scripts/104598/7 "2025-03-25T14:58:58Z")

</div>

I’ve been using Julia for 3 years this is the first time I realized you can do multiline comments. I remember when I learned C in college multiline comments was learned on the first day. I assumed there was no multiline comments just like Python, which resorts to using ugly strings.

Looks like `#=`, `=#` has been around for more than a decade. I wish this was played up more when introducing Julia’s syntax to Python users.