# Literate.jl: treat comments as comments

**URL:** <https://discourse.julialang.org/t/literate-jl-treat-comments-as-comments/122832>\
**Category:** General Usage\
**Created:** [November 20, 2024, 7:03am UTC](https://discourse.julialang.org/t/literate-jl-treat-comments-as-comments/122832 "2024-11-20T07:03:41Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![cstjean](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cstjean/32/1444_2.png) [@cstjean](https://discourse.julialang.org/u/cstjean)\
**Post date:** [November 20, 2024, 7:03am UTC](https://discourse.julialang.org/t/literate-jl-treat-comments-as-comments/122832/1 "2024-11-20T07:03:41Z")

</div>

In Literate, if I have code like

```julia
function foo(vec)
    # print the elements
    for x in vec
        print(x)
    end
end

```

`Literate.markdown(; flavor=Literate.DocumenterFlavor())` will treat the comment as some separator, and output two `@example` blocks: one `@example` block containing just `function foo(vec)`, then the comment in plain text, then another `@example` block containing the rest of the code. Then obviously Documenter chokes on it; neither block is syntactically correct. Is there any way around that? If I write my comment without a leading space, then it’s treated correctly, but it’s rather ugly.

Obviously, I’m happy to have top-level comments be treated as markdown. But comments inside of code blocks should be left as comments…

---

<div class="post-metadata">

**Author:** ![hexaeder](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/hexaeder/32/24403_2.png) [@hexaeder](https://discourse.julialang.org/u/hexaeder)\
**Post date:** [November 20, 2024, 7:17am UTC](https://discourse.julialang.org/t/literate-jl-treat-comments-as-comments/122832/2 "2024-11-20T07:17:47Z")

</div>

Lines marked with double `##` will show up as „normal“ comments iirc.

> **[2. File format · Literate.jl](https://fredrikekre.github.io/Literate.jl/v2/fileformat/#Syntax)**
>
> Documentation for Literate.jl.

> Since #-lines are treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [November 20, 2024, 8:11am UTC](https://discourse.julialang.org/t/literate-jl-treat-comments-as-comments/122832/3 "2024-11-20T08:11:49Z")

</div>

It would be possible to make indented `#` comments be comments, but then that would be inconsistent with toplevel comments which would still have to be `##` comments.

The reason for supporting indented `#` markdown is that Literate (and Documenter) supports splitting up expressions into incomplete parts. Here is an example input:

```julia
# This is the main function
function main()
    #+
    # First we call foo
    f = foo()
    #+
    # Then we call bar
    b = bar()
    #+
    # Finally we return the sum
    return f + b
end

```

with the markdown output:

`````markdown
This is the main function

````@example main; continued = true
function main()
````

First we call foo

````@example main; continued = true
    f = foo()
````

Then we call bar

````@example main; continued = true
    b = bar()
````

Finally we return the sum

````@example main
    return f + b
end
````

`````

In version 1 of Literate the explicit continued-expression markers (`#+`) were optional, but since version 2 they are required so it would again be possible to require markdown to be dedented (but again, would be inconsistent with top level comments).