We are currently planning to migrate to a different platform for the forum. We will announce this fact both here and on Twitter, once we have settled on a solution.

Is Zettler documentation written on Zettler?

Hi,

I have recently started using Zettler and need to understand whether I can write the kind of documentation that is written about Zettler (docs.zettler.com) on Zettler. If so, how is the documentation set up on Zettler?

Comments

  • The source files for the documentation can be found on Github: https://github.com/Zettlr/zettlr-docs

    As you can see there, these are all Markdown files (with some styling and configuration), so yes, all of these files can be edited by Zettlr. If you are impressed by the design of the docs.zettlr.com site, then you may want to take a look at MKDocs.

  • Yes, as long as I'm not fixing small typos (which I do directly on GitHub), I'm writing the documentation in Zettlr.

  • Thanks for replying @hendrik and @canpolat,

    @hendrik, how are you are organizing your Zettlr project? and what is your workflow?

    I see that markdown in Github documentation does not use the double square bracket notation for links as Zettlr does, but rather uses standard markdown syntax. Is the documentation that I see on Github the same as your working copy? or do you export your working copy?

    Secondly, some of the documentation pages are long (eg. https://github.com/Zettlr/zettlr-docs/blob/master/docs/en/reference/settings.md). Is this page the same as in your working copy, or does your working copy break up sections into individual markdown files and then recombine them for output? The latter approach is along the lines of Zettlekasten, and is helpful for focus in general.

    Lastly, linking in Zettlr is done through the note id, which is very convenient because it frees me up to adjust the filename now or later. However, linking in markdown is done via filename. I can't figure out how to avoid problems when the filename is not the same as note id, such as in your GitHub documentation. Do you use note-id based links for documentation? Can you comment on this please.

    As a related question, what is your file naming conventions? Out-of-the-box Zettlr uses note-id. Zettelkasten.de recommends note-id note-name, which is more convenient. The nice thing about Zettlr is that I can make use of both. My question is if you know how to make this interoperable with other markdown-based applications so as not to be Zettlr dependent. GitHub is an example.

    I am asking because documentation is one of the projects that I want to move to Zettlr and I don't want export problems.

  • Okay, there's a lot to unpack, but let me attempt!

    1. There are three locations where the documentation is. First is the GitHub repository. Everything is stored there for easy access and collaboration (because oftentimes, users are more adept at spotting holes or wrong information in the documentation, and so they can offer assistance). Second is the actual documentation page, where the GitHub repository is being exported to. Third are the repository clones on each contributor's computers.
    2. The documentation repository is structured so that it works with MkDocs as canpolat has argued. So a lot of the file structure is being dictated by the way MkDocs works. It's pretty straight forward. Many projects use, e.g., Jekyll via GitHub pages for their documentation, and that system has a little bit different requirements, but basically it also needs a specific file structure, so these repositories will look a little bit different.
    3. For MkDocs, there are two things necessary. First a configuration file that defines, e.g., the template, the page title, and the navigation (for Zettlr in the config subdirectory). Secondly, the actual contents of the documentation, which reside in the docs subdirectory (separated by language).
    4. Within each of that language subdirectories the actual contents are being stored in Markdown that we can edit.
    5. This means, the docs/-subdirectory is the actual root for the documentation, the rest is config and some wrap-around stuff that is necessary, but not written in Markdown. And this means for practical implementation with regard to the links:
    https://github.com/Zettlr/zettlr-docs/blob/master/docs/en/reference/settings.md
                                                      ^--- This is the starting root, which means into Zettlr you can import the "docs" subdirectory only
    ... and this will become:
    https://docs.zettlr.com/en/reference/settings
    
    So the whole
    https://github.com/Zettlr/zettlr-docs/blob/master/docs
    
    is being replaced by
    https://docs.zettlr.com/
    

    You can find out what is happening by having a look at the GitHub Actions workflow that is run on every push. Please refer to the documentation on GitHub to read more about that as it's somewhat unrelated to Zettlr.

    Now to the links: Zettlr supports two types of links, and it is important to know the differences:

    1. Regular Markdown links with the syntax [Link text](Link target)
    2. So-called "internal" links with the syntax [[link target]]

    The latter look a lot like MediaWiki links as being used on Wikipedia, but work differently. They are a form of "fuzzy search" because they will work even if you remove the file and the link doesn't uniquely identify any file anymore, as it will also trigger a search. This is heavily Zettlr-based behaviour that no other app features as far as I know. This means you have to know how they work (see the documentation for more info on them). The benefit, however, by keeping the default settings (two square brackets as encapsulation) these links will also work to some extent with other programs that support this fuzzy-linking, e.g. Obsidian, which is oftentimes recommended as a companion to Zettlr.

    The Zettlr documentation uses regular Markdown links to refer to different files, and yes, this means the filenames should not change, and if they do, all links need to be updated. However, that is the recommended way to create "hard" links to other files, and will be recognized by almost all parsers. The internal links are much different, because they allow you to link based on ID and not based on filename, which means the underlying file structure can change as much as you want, the only thing that needs to stay is the ID used.

    TL;DR: Links are always "hard" and specific, because they link to a specific target. Regular Markdown links always link to filenames, whereas internal links allow you to create the "hard link" based on information within the file, hence they can be detached from the file structure and attached to your internal Zettelkasten structure.

    Therefore:

    I can't figure out how to avoid problems when the filename is not the same as note id, such as in your GitHub documentation. Do you use note-id based links for documentation?

    You can't avoid all problems. If you link using the Zettelkasten-link-syntax, and change an ID, you must update your links as well. if you link using regular Markdown links, you must update those if the filename changes. So there's always some amount of work to be done.

    However in general: Zettelkasten links are highly specific to a small subset of apps and can therefore not be expected to work with every parser. Regular Markdown links on the other hand, are. That being said: If you want to collaborate with other people on something that will be put online, such as documentation, always use regular Markdown links. But if you work on a system that is not being "exported" somewhere, and you know that other people collaborating with you know about the concept of internal links and use similar programs, you can use these.

    I hope that somewhat lengthy explanation helps!

  • Thanks a lot for your explanation @hendrik. I understand now that double square bracket links are interoperable only to a small subset of applications and even that only if the filename is the same as link ID (I think this is the case in Obsidian).

    IMO for personal notes management linking based on ID (and not filename) is the way to go. It gives maximum flexibility to change filenames and as far as I can see there is little need to change file ID. I think you are ahead of the pack in this regard and that support for ID-based linking independent of filename will come to other .md based notes management software. At this time my best guess for a future standard is YAML-based IDs.

    I looked into whether there is an accepted YAML convention for denoting IDs, and so far could not find one. One post used a tag called 'note-id', another post used a tag called 'id'. Do you have any recommendations of a convention to use for YAML-based ids that you think will in time be accepted by other .md based notes management software?

    Lastly, do you have a way of exporting (or refactoring) multiple atomic Zettlr files into a single lengthy file, such as the settings page in the documentation? This question was missed from my previous post.

  • I also think YAML frontmatter has huge potential and hope that it will be the ultimate place for setting metadata.

    I'm not Hendrik, but let me attempt to comment on some of your questions:

    1. I don't see any standards about defining id metadata, either. Possible candidates are id, uid and guid. In my notes I use zid (Zettelkasten/Zettlr ID). As long as you are consistent, I don't think that would be a problem in the future. It should be fairly easy to do a find/replace for multiple files. BTW: If Zettlr cannot find an ID matching the pattern defined in your preferences, it will look in the contents of the file and pick the first string that matches it. So, when you place the ID at the top of your YAML frontmatter, you are free to rename your files. Maybe you knew this already, but it was a surprising find for me in the documentation.

    2. There is a discussion in GitHub about embedding notes. There is also the possibility of using projects for exporting the output of multiple files into a single file. But, none of these are used for Zettlr documentation page. That page uses MkDocs configuration files to stitch things together.

  • Thanks for your reply @canpolat You have clarified the points I was asking Hendrik.

    Regarding the first point, I have not read this documentation page, but observed the functionality. I agree with you about YAML - the placement of ID at the top has a lot of potential for interoperability as well as implementation of external functionality based on IDs. I am surprised this is not in common use for internal links for .md based notes management software.

    Thanks for pointing me to the GitHub discussion. The discussion is exactly on the same feature I was asking for, and the suggestions make sense.

Sign In or Register to comment.