Hello all!

I’m documenting a small FOSS project, and I’m looking for some soft that translates a documentation into a web page.

Something simple, with a side board that links the pages/titles/sub-titles, and is PC and Mobile compatible. Basically images, italics, bold and links, with titles and subtitles, would be nice 🙂.

Like the Lemmy install guide for example: https://join-lemmy.org/docs/administration/install_docker.html

Any recommendations?

Thank you all!

  • n0xew
    link
    42 months ago

    You can have a look at hugo, with some simple theme like hugo-book

    • @ValmondOP
      link
      12 months ago

      The example site is a bit cluttered, but maybe that’s just optional, will check out, thanks!

    • @ValmondOP
      link
      12 months ago

      Tried it but how do you actually build the static html files? It’s only explaining how to run the site through some sort of java script machinery?

      Nice otherwise, thanks!

  • Ephera
    link
    fedilink
    22 months ago

    That Lemmy guide uses mdBook: https://rust-lang.github.io/mdBook/

    It originates from the Rust ecosystem, but it’s basically language agnostic.
    You basically provide it Markdown files in a certain file structure and then it does the rest. Really easy to use.

    • @ValmondOP
      link
      12 months ago

      Very nice! Seems like a hassle to install though, but I’ll definitely check it out, looks exactly what I’m looking for (as long as you can throw in images, didn’t see that at my first very brief glance).

      • Ephera
        link
        fedilink
        22 months ago

        Hmm, I think, you can download one of the .tar.gz files from here: https://github.com/rust-lang/mdBook/releases
        Unpack it and then just run the executable that’s inside.

        And yes, images are absolutely possible.
        You can just place the image file in the file structure and then in your Markdown file, you can use this syntax:

        ![Optional description for sight-impaired users](relative/path/to/image.png)
        

        I usually create an “images” sub-folder next to the Markdown file, then it’s just:

        ![](images/something.png)
        
        • @ValmondOP
          link
          22 months ago

          Very nice, will definitely check out!

          Seems like exactly what I’m looking for.

        • @ValmondOP
          link
          22 months ago

          Update, works wonders thank you so much! 💖

  • grandel
    link
    fedilink
    22 months ago

    I like mkdocs because it generates the entire site from markdown files

    • @ValmondOP
      link
      1
      edit-2
      2 months ago

      Thanks, I just tested mdBook and it does just that, it’s great!

  • Onno (VK6FLAB)
    link
    fedilink
    12 months ago

    My go-to for this is pandoc, it takes markdown and can generate html, pdf, word, OpenOffice and other formats.

    Because it uses markdown, you can use version control and grep on your documentation and include it with your source code.

    • @ValmondOP
      link
      22 months ago

      Thanks, but for now I think that looks like overkill for my small needs.

        • @ValmondOP
          link
          12 months ago

          I haven’t tried yet, but it seens like a lot to just get up and running, will check out if that other one doesn’t make static websites.