# Using notebooks or Julia markdown with Documenter.jl

**URL:** <https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024>\
**Category:** General Usage\
**Tags:** question, jupyter, documenter, weave, notebooks\
**Created:** [September 4, 2024, 9:33am UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024 "2024-09-04T09:33:39Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![msw](https://avatars.discourse-cdn.com/v4/letter/m/b782af/32.png) [@msw](https://discourse.julialang.org/u/msw)\
**Post date:** [September 4, 2024, 9:33am UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024/1 "2024-09-04T09:33:40Z")

</div>

I would like to use notebooks or Julia markdown (jmd) with Documenter.jl similarly to [mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter), but I cannot find any tutorials or examples on how to do so.

My first idea was to use Weave.jl to generate markdown from jmd files. Then, Documenter.jl would do the rest. I believe this would work in production. However, when developing using live reload, I start an endless loop. LiveServer.jl detects a change, it triggers my `make.jl` script which use weave to generate markdown. `LiveServer` detects this change, and the cycle repeats. Additionally, having generated files among my other files is perhaps not a good practise either?

Therefore, I thought of weaving into temporary directories (e.g. using `mktempdir()`). However, Documenter does not recognise files outside the `docs` folder (see [issue #551](https://github.com/JuliaDocs/Documenter.jl/issues/551)).

Does anyone have other ideas?

---

<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:** [September 4, 2024, 9:39am UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024/2 "2024-09-04T09:39:52Z")

</div>

Utilize the `skip_dirs` and `skip_files` keyword arguments to `servedocs`, see [LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub](https://github.com/tlienart/LiveServer.jl/blob/eec3d5b23d16e296ba55c4f99084c1814bee5165/src/utils.jl#L199-L201).

Example usage: [Ferrite.jl/docs/liveserver.jl at 241d181490511e67fcb5d723b67ecb1c22cbe363 · Ferrite-FEM/Ferrite.jl · GitHub](https://github.com/Ferrite-FEM/Ferrite.jl/blob/241d181490511e67fcb5d723b67ecb1c22cbe363/docs/liveserver.jl#L16-L46)

---

<div class="post-metadata">

**Author:** ![Janis\_Erdmanis](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/janis_erdmanis/32/10869_2.png) [@Janis\_Erdmanis](https://discourse.julialang.org/u/Janis_Erdmanis)\
**Post date:** [September 4, 2024, 10:50am UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024/3 "2024-09-04T10:50:55Z")

</div>

I recently tried to use `skip_dirs` with a custom Literate.jl combination and got infinite loop anyway. Looking in a code I saw that file watcher does not respect those arguments as can be seen in the code: [LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub](https://github.com/tlienart/LiveServer.jl/blob/eec3d5b23d16e296ba55c4f99084c1814bee5165/src/utils.jl#L268)

A thing that works though is to clean up all generated files before starting the live server as then those are not registered with the file watcher.

---

<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:** [September 4, 2024, 11:04am UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024/4 "2024-09-04T11:04:31Z")

</div>

They might be added to the watcher, but the callback filters them out here: [LiveServer.jl/src/utils.jl at eec3d5b23d16e296ba55c4f99084c1814bee5165 · tlienart/LiveServer.jl · GitHub](https://github.com/tlienart/LiveServer.jl/blob/eec3d5b23d16e296ba55c4f99084c1814bee5165/src/utils.jl#L34-L41). If you have a MWE where this doesn’t work I can have a look.

---

<div class="post-metadata">

**Author:** ![Janis\_Erdmanis](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/janis_erdmanis/32/10869_2.png) [@Janis\_Erdmanis](https://discourse.julialang.org/u/Janis_Erdmanis)\
**Post date:** [September 4, 2024, 6:30pm UTC](https://discourse.julialang.org/t/using-notebooks-or-julia-markdown-with-documenter-jl/119024/5 "2024-09-04T18:30:05Z")

</div>

I got `skip_dir` to work with my setup. The issue was that MacOS file paths are case-insensitive, and I made a mistake in specifying the path. The generated files could be removed just fine; however, the `startswith(fp, dir)` would always return false 😔.