Problem

The desktop app is flagging almost 200 issues with our project. Most if not all are isseus with READMEs in the node_modules directory. Obviously, we don't own these and they are not included in the final build of the site.

Currently, the issues list is basically useless given the quantity of noise.

Example

Proposed solution

Two ideas:

1. Add an ignores key to doctave.yaml that allows you to specify directories to ignore. This should come with node_modules already added
2. Ignore node_modules by default and don't allow any customisation

I noticed that this package is not published on crates.io. I think it'd be good to add this, to simplify installation and ensure that there will be a nice backup.

Is this something that could be done?

I downloaded the latest release & unzipped the file, but I can't open the .exe file.
Win 10 64bit

I am trying to test Doctave on Windows. Have initiated the website, however after editing some of the files I am getting the following error. Can you tell me how can I resolve this error.

I recently found your Project and decided to use it for my Obsidian notes workflow. So I can generate a static version to host.
But I found the need to exclude specific files or folders.

Doctave sadly doesn't allow ignoring specific folders, is it possible in the future to make a .doctaveignore?

The build process crashes and panics when specifying the README.md file as a path.

Example:

// >> doctave.yaml
---
title: "Repo"
navigation:
  - path: docs/README.md

$ RUST_BACKTRACE=1 doctave build                                                                                                                                                                                                

at 14:37:03
Doctave | Build
Building site into /home/msc/Code/go/src/oceanbolt.com/spire-vessels/site

thread 'main' panicked at 'No matching link found', src/navigation.rs:47:26
stack backtrace:
   0: rust_begin_unwind
             at /rustc/c8dfcfe046a7680554bf4eb612bad840e7631c4b/library/std/src/panicking.rs:515:5
   1: core::panicking::panic_fmt
             at /rustc/c8dfcfe046a7680554bf4eb612bad840e7631c4b/library/core/src/panicking.rs:92:14
   2: core::option::expect_failed
             at /rustc/c8dfcfe046a7680554bf4eb612bad840e7631c4b/library/core/src/option.rs:1578:5
   3: doctave::navigation::Navigation::customize
   4: doctave::navigation::Navigation::build_for
   5: <doctave::site::DiskBackedSite as doctave::site::Site>::build
   6: doctave::build::BuildCommand::run
   7: doctave::main
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

It is not a major issue, but it caused a bit of debugging for me trying to get the custom navigation to work. It was unclear that it was the README.md inclusion that caused the error. Suggesting to either ignore the file if specified, or provide a more helpful error.

provides a default 404 page and enable custom not found pages.

e.g.

title: my project
not_found_page: docs/404.md

It appears the generated site can only be deployed to the root of a website, ex: "https://example.com/index.html", because leading slashes are used on all assets. What do you think of supporting generating the site so it can be deployed to a path, ex: "https://example.com/documenation/index.html"?

Hi Niklas,

I reached out a few months ago. I have some time so giving doctave a go.

Our repo is structured so that docs live next to the code, e.g.:

app/
  - README.md
  - index.tsx
  - components/
      - README.md
      - NavBar.tsx

It seems that doctave uses the file name "README" when populating the navbar. Is docs in README a use-case for doctave? If so, it might be helpful to use either the title of the README or use the directory name instead of "README"

Follow up from:

• #16

The creator of the issue wanted a way to override the prism.js version in order to get support for his language choice. While I don't feel Doctave should allow this by default (it goes against the idea of "batteries included"), the problem of not supporting their languages is a real problem that should be solved.

The issue is that prism.js grammars are non-trivial in size. Including all languages increases the bundle size, and given that most people will only require 1 or 2 languages, this seems wasteful.

I think there are 2 options to look into here:

Use the autoloader feature of Prism to load at runtime only the languages that are on the page.
This does not decrease the final bundle size, but at least we don't have to transfer all grammars on every request.

Detect which languages are used on each page and dynamically include into the final bundle only the used languages.
Seems complicated, but this would have the added benefit of reducing the deployed bundle size too.

Having a default tag taxonomy with tags displayed on each page and pointing to the corresponding tag index.

Extensive explanation of the tag support idea: intuit/Ignite#126 (tags display on pages, tags index, tags list, etc.)

Examples

Examples in other staticgen:

• Retype (documentation) https://retype.com/configuration/page/#tags
• Hexo (blog) https://hexo.io/docs/front-matter

Screenshot on retype:

Tags button embedded on a page:

A tag index (https://retype.com/tags/config/):

The index of all tags (https://retype.com/tags/):

Examples on my Hexo blog:

Tags on an article:

A tag index (https://blog.raw.pm/tags/eop/):

The list of all tags (https://blog.raw.pm/tags/):

A tag cloud widget:

When I release a new build landing page and all index.html work just fine. But all other HTML (Markdown) files are not showing.

For example: I have a folder called Rezepte. So the navigation link is /Rezepte, which works, because a README.md file is converted to an index.html.

However the Doctave.md file within that folder is not reachable via the navigation. The link is /Rezepte/Doctave but this is not a file. /Rezepte/Doctave.html on the other hand works as expected.

Is this a bug in doctave or in my setup? I use valet locally to run dev sites.

First, let me start by saying thank you for this great project. It was very easy to get started. I had my first demo website generated within minutes!

However, there is one think i run into:

Would it be useful to add a configuration option to use the first markdown headline in a file instead of the filename?

I know that i can achieve the desired outcome by adding

---
title: My.Namespace.Test
---

on top of this each file.

My use case is the document generation for a few libraries. Unfortunately, i can not change the README.md files because there are used in different places. That's why i would prefer a configuration toggle.

this looks like a great tool, but I really can't figure out how to get it install it!

Ive downloaded the .exe file. ran it, ran it via my bash cli, ran it via powershell, downloaded rust and cargo, tried to install that way but then i got an error saying i needed some visual studio tools...

There must be a simple step that I dont know about here?

If you do doctave init and serve the default example.md, the sample diagram's arrows are too dark in dark mode, making it hard to see.

Hi!

I tried to build a site using doctave and here's what I get: https://alestsurko.by/kotoist/

Check out the console.

The repo is here: https://github.com/ales-tsurko/kotoist

I've added .nojekyll and CNAME. Without CNAME I had the same result.

Doctave comes prepackaged with a version of prism that has a subset of languages for highlighting in code blocks. If we want to change the version of prism used, all we'd have to do is edit the prism.js file. (FWIW, I was interested in YAML and BASH highlighting). I'd expect if I:

• Add the custom prism.js file I wanted in docs/_include/assets
• Running doctave serve should reflect the change
• Running doctave build --release should reflect the change: the file should be copied to site/assets/prism.js

But neither of the above occurs.

This may be as simple as allowing any file in docs/_include/assets to be copied over at the latest possible step.

i.e., switching these two lines:

Seems both are using the .content class, which is a bit too generic. This is causing some code blocks to be rendered incorrectly.

Going to add some Doctave prefixes to fix this instance.

Doctave is currently using mermaid.js with version 8.8.0. The latest release of mermaid.js is 8.13.3.
I am currently observing differences in mermaid live editor and the doctave rendered pages because of the version change.

In general, is it possible to keep these javascript libraries updated via a build script ?

Running "doctave serve" in the command prompt gives me this:

Although, the browser does not seem to connect:

Is there any way to address this? Am using Windows 10 :) Thank you!

I have sone long .md file with long TOC. When scrolling down, the right hand panel stops after a few lines. Actual content and left panel scrolls OK.

Platform: MacBook
Browsers: Safari, Vivaldi

I'd really like for the documentation root to be configurable.

If that's a non-starter, I'd really like for the error messages produced when attempting to find navigation to be refined.

Currently, using this doctave.yaml

---
title: "My Project"

navigation:
  - path: subdir1/
    children: "*"

produces a rather confusing error message (I included the backtrace for good measure).

Doctave | Serve
Starting development server...

thread 'main' panicked at 'No matching link found', src/navigation.rs:52:26
stack backtrace:
   0: rust_begin_unwind
             at /rustc/59eed8a2aac0230a8b53e89d4e99d55912ba6b35/library/std/src/panicking.rs:517:5
   1: core::panicking::panic_fmt
             at /rustc/59eed8a2aac0230a8b53e89d4e99d55912ba6b35/library/core/src/panicking.rs:101:14
   2: core::option::expect_failed
             at /rustc/59eed8a2aac0230a8b53e89d4e99d55912ba6b35/library/core/src/option.rs:1615:5
   3: core::option::Option<T>::expect
             at /rustc/59eed8a2aac0230a8b53e89d4e99d55912ba6b35/library/core/src/option.rs:698:21
   4: doctave::navigation::Navigation::customize
             at /home/jona/projects/doctave/src/navigation.rs:50:42
   5: doctave::navigation::Navigation::build_for
             at /home/jona/projects/doctave/src/navigation.rs:23:26
   6: doctave::site_generator::SiteGenerator<T>::run
             at /home/jona/projects/doctave/src/site_generator.rs:45:26
   7: <doctave::site::InMemorySite as doctave::site::Site>::build
             at /home/jona/projects/doctave/src/site.rs:115:9
   8: doctave::serve::ServeCommand::run
             at /home/jona/projects/doctave/src/serve.rs:37:9
   9: doctave::serve
             at /home/jona/projects/doctave/src/main.rs:102:5
  10: doctave::main
             at /home/jona/projects/doctave/src/main.rs:52:33
  11: core::ops::function::FnOnce::call_once
             at /rustc/59eed8a2aac0230a8b53e89d4e99d55912ba6b35/library/core/src/ops/function.rs:227:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

Since it's not possible to change the documentation root, I cannot compile the documentation, even with an (effectively useless) README.md present in the docs subdirectory.

We should add a feature where we verify that internal links within a project are not broken.

Current plan would be that when running doctave build, we'd show any errors and fail the build if there are broken links, with a flag that allows for ignoring the error status.

I'm going to narrow this down to internal links only for now, as going over the network to check external links has lots of additional complexity (servers can go down, some internal systems may not be accessible from CI, etc).

First headline is not recognized when File encoding is UTF-8-BOM

Works perfect after changing encoding to UTF-8

When generating a new Doctave site on Windows, doctave init, the Examples page is generated with Windows line endings. These line endings prevent the title from being parsed by Doctave and instead are included as markdown content, as if it were just markdown content. The same issue occurs when generating new files on Windows, because they also contain Windows line endings. After changing the files to Unix line endings then the title is parsed by Doctave and the page's title is displayed as expected.

Currently we rewrite the whole documentation site to disk on every change. It would be much better for us instead to generate the HTML in memory, and have the web server serve pages without touching disk.

This would both improve performance and spare the disks of users of extra work.

Just wondering if there is still active development on this project before I use it for my own docs.

Thank you.

Like mdbook and others, we should add support for mathematical notation.

MathJax seems like it could be a good option. It could be integrated similarly to how we do with MermaidJS - bundle the minified JS in the binary and serve it.

Discussion found here: https://www.reddit.com/r/rust/comments/qpeblj/comment/hjuxq5d/

I have a README.md page that links to two internal docs pages:

- [Developing](doc/dev/README.md):
- [Bazel](doc/dev/developing_bazel.md):

The first link to doc/dev/README.md doesn't work in doctave because doctave serves that page from doc/dev (no trailing /README.md).

The second links works as expected.

Currently the parser only supports frontmatter in yaml format:

---
title: "my title"
---

For compatability with other SSGs it would be cool to also support TOML format in the frontmatter

+++
title= "my title"
+++

The two are equivalent, but the toml is surrounded by +++ instead of ---.

As an example Zola SSG (getzola.org) supports both.

I was working on making a nix package for dotave and notcied that revision tagged as 0.4.2 has an outdated Cargo.lock file.

This prevents building this package offline and in a reproducible way. This is very easy to prevent in the future by using --frozen flag for cargo during CI.

looks the only thing that is different is version of doctave itself. i guess you tag a little bit to early ?

A nice to have would be to be able to set a path for doctave build --release.

As a developer this removes the need to script a copy command into my tool chain simply to copy the contents of /site into /public/docs

Hi there, just stumbled over this issue. If I have inline code in a heading, all succeeding text will be truncated.

To reproduce create a file with the contents:

# Foo `bar` baz

The right On this page navigation will have a single item of Foo , missing the rest of the title.

Maybe we could create a new version field in doctave.yaml ? This field would be optional, meaning that if it is not set, no version appears (like it is now). If it is set, it could be displayed in the upper left-hand corner, maybe like in one of these examples:

• Directly with the title
  
• Under the title
  
• Next to the title
  

I recommend making this yaml field a string rather than an int or a float, to handle versions like 3.0-alpha easily.

Hey :)
Thanks again for this project!
I started to play a bit with the source code (recent master, version 0.4.2) and noticed when in dev mode:
cargo run serve or ./target/debug/doctave serve
And editing one of the files of "docs" e.g. tutorial.md
The reload logs indicates the site rebuilt but the browser didn't reload the page

File /Users/.../.../doctave/docs/tutorial.md updated. Site rebuilt in 423.13685ms File /Users/.../.../doctave/docs/tutorial.md~ deleted. Site rebuilt in 434.936333ms

It won't happen when using the globally installed cli I installed with brew
doctave --version Doctave 0.4.2

System info:
Darwin C02F54NDMD6T 21.4.0 Darwin Kernel Version 21.4.0: Mon Feb 21 20:34:37 PST 2022; root:xnu-8020.101.4~2/RELEASE_X86_64 x86_64

What am I missing? :)
Thanks!

Hello

I am tried to build a documentation site with the examples.md page as well as a few new pages added to it. However after building the site in release mode the contents of the html pages are distorted also the diagrams drawn with mermaidJS are not visible.
Can you help me out with this issue.

Hi!

First just want to say thanks for making this package, it's super slick and overall way easier to use than previous documentation builders I've tried.

I've just gotten to the point publishing my docs using the commands specified in the tutorial:

doctave build --release
gh-pages -d site

And this does work. GitHub pages picks up the documentation but it seems to conflict with some of the previous websites I've got set up.

The documentation I'm trying to build looks like this: Lorikeet
As you can see, it hasn't loaded correctly and I think this is because the directory structure seems to point to stuff in my github about me page thing: Rhys Newell

I've tried using the base_path variable in the doctave.yaml but that didn't seem to work. If you've got a fix for this please let me know

Cheers,
Rhys