vimdoc-notes-website.txt organizing and publishing notes with vim

Original Author: Sahil Gautam <printfdebugging@gmail.com>
Homepage: <https://printfdebugging.in/>
License: GNU GPL v2

==============================================================================
CONTENTS

    1. What is VimDoc                                           what-is-vimdoc
    2. Why VimDoc and not Anything Else                             why-vimdoc
    3. Hosting Notes on a Website                        hosting-notes-website
    4. About vimdoc2html scripts                                   vimdoc2html
    5. My Notes Workflow                                     my-notes-workflow

==============================================================================
What is VimDoc                                                  what-is-vimdoc

    vimdoc is an umbrella term which covers all the help page infrastructure
    in vim. vim's help files are of filetype=help, and vim provides
    highlighting for the headings, links, code etc. :helptags dir creates a
    tags file for the help files in dir, read about ctags on the internet
    to know about tags and tags file.
    
    from my understanding there are two types of links, the star links and the
    pipe links. a pipe link takes you to a star link of a matching name,
    that's it. all this requires no external tool but vim.

==============================================================================
Why VimDoc and not Anything Else                                    why-vimdoc

    i tried everything else, i tried emacs's org-roam, obsidian, standalone
    markdown files, nothing worked. org-roam were bulky, i am a vim user and
    for using org notes, i had to have emacs, and emacs was very distracting
    it's such a good piece of software (but slow), i couldn't use it just part
    time.

    vimdoc on the other hand is very minimal, very featureful, very well
    organized, universal (for vim users), without any bells and whistels...
    and since all the links are just tags, there are scripts out there like
    vimdoc2html which in a few lines of python, create a website out of
    vimdoc notes.

==============================================================================
Hosting Notes on a Website                               hosting-notes-website

    i use gitlab to host my website, and vimdoc2html scripts to export from
    vimdoc to html, it works very elegantly. i will make my notes repository
    public if that helps (see https://gitlab.com/printfdebugging/notes)

    the gitlab ci file creates an out directory and runs the publish
    script. the publish script creates html file for each txt file using
    vimdoc2html.

==============================================================================
About vimdoc2html scripts                                          vimdoc2html

    thanks to @xaizek https://github.com/xaizek/vimdoc2html for creating these
    scripts. if you know some python and have even a little experience in
    programming and some patience, then you will really easily be able to
    understand and modify the scripts, they are not that complex/long.

    i modified my copy of vimdoc2html to support interlinking between
    different files (see https://github.com/xaizek/vimdoc2html/issues/13).
    it just works flawlessly, looks the same, works the same both online and
    in editor.

==============================================================================
My Notes Workflow                                            my-notes-workflow

    i have an index.txt file which links to all other notes. these notes
    interlink to each other to provide some context and avoid repetition. i
    organize notes based on months, so the directory structure looks something
    like this...

        notes
        ├── 2025
        │   └── 04
        │       ├── breaking-changes.txt
        │       ├── vimdoc-notes-website.txt
        │       └── ....
        ├── index.txt
        ├── publish
        └── scripts
            ├── helpztags
            ├── vimd2h.py
            ├── vimdoc2html.py
            └── vimhelp.css

    each txt file starts with a header line followed by a author and licence
    statement. then we have a table of contents, and the content itself...

==============================================================================
vim:tw=78:ts=8:ft=help:norl:fdm=marker:fmr=<<<,>>>:ma:noro