3

Notice, I don't want

  • to publish on [1]git
  • to use Wiki format, Wikipedia, or any...
  • to use any service as a third party
  • to use the paid Obsidian service Publish

My idea came from the Obsidian website itself, obsidian.md.

I want to do the same as they did in the help pages, but by myself.

  • able to create a series of .md files interconnected to which other as a website.

  • notice they're all in .md format, they need to be in the .md format

  • they need to have the same markdown capabilities, like linking to other files, headers, etc.

[1] Since I don't understand git, I just don't want my page looking awkward, it needs to be clean [EDIT: here I meant anything by github.com] but the reason is "I don't want to be dependent" on any website or a third party (in the case this went down one day, or, it turns into a pre-plan paid service in the future)

4 Answers 4

3

At our company, we use Docusaurus to serve documentation pages written in Markdown. It's an open source application which has all Markdown capabilities Stack Exchange has, plus a few nice additions; it's certainly possible to link to other files. Incidentally, we do use Git for version control, but that is not required.

You should be able to set it up in 5 minutes, here are the instructions. You'll need Node.js to run it locally. When you're finished editing (or finished copying over your current Markdown files to the /src/pages/ folder), you can build the project so you can deploy it to your hosting location.

5
  • It's interesting, I'll have to read a lot to understand this. But it's a paid application? I don't like much Javascript. And I want to do things from scratch, instead of depending on 100 libraries for many functions. I believe the more dependent the less efficient as a programmer. Then I quickly saw an option for Python, that's rather my choice. Feb 22, 2022 at 2:10
  • I know there is a manual, but can you give a few steps to not getting lost for being able to create the markdown website, like 1. I have this folder of .md files 2. set the configuration 3. final steps. For me and everyone else, so I can mark it as the right answer. Feb 22, 2022 at 2:19
  • 1
    I've updated my answer with some additional details, I hope you'll be able to figure out if it works for you. If you found another way, don't forget to post it as another answer, for the benefit of other users. It's OK to self-answer on Stack Exchange.
    – Glorfindel
    Feb 22, 2022 at 12:33
  • 1
    I believe your answer is pretty much close for what I want, I'm not sure if I'll need React and Javascript skills. But I'll mark as right because it's helpful. Thanks! Feb 22, 2022 at 17:21
  • 1
    You'll certainly don't need React, and JavaScript/Node.js is only necessary for the command line tooling, you won't need to write anything but Markdown.
    – Glorfindel
    Feb 22, 2022 at 18:05
2

I use the tool MkDocs for documentation-style websites with source documents stored as Markdown files.

Personally I track my source files with git, but MkDocs is ignorant about how source is stored, it cares only about content itself and how it is organized in directories.

A closely related alternative to MkDocs is MdBook. Same core idea, but where MkDocs is implemented in Python, MdBook is written in Rust and borrows some of the concepts from that different community, e.g. expressing metadata as TOML instead of YAML

Other documentation systems exist but the above seem closest to your requirements. E.g. Sphinx (quite popular for documenting Free Software projects which uses ReStructured Text by default but has a rich set of plugins including several options to include Markdown sources). And the many many MANY static website compilers where the most popular nowadays is Hugo, where the more mature of them have plugin systems that you can use to piece together your very own unique documentation structure.

All applications mentioned here are Free Software (a.k.a. Open Source), which implies that they are free-of-charge to use on your own (and also free to setup for-charge services around).

0

If you're ok with a (static) HTML generator which processes the markdown whenever you make a chance, you could try Jekyll:

Transform your plain text into static websites and blogs.

The Jekyll gem makes a jekyll executable available to you in your terminal. The jekyll program has several commands but the structure is always:

jekyll command [argument] [option] [argument_to_option]

Examples:

jekyll new site/ --blank
jekyll serve --config _alternative_config.yml

Typically you’ll use jekyll serve while developing locally and jekyll build when you need to generate the site for production.

and of course it supports markdown (and other formats I believe).

1
  • Thanks for your answer but I don't want to generate html. That needs to be in .md format, the reason is to keep the markdown capabilities. I'm not sure how this works yet. But I had a decent reading of others how-to's and found that it's possible. Mar 14, 2022 at 13:18
0

You say not using git.

Therefore you could use github, but not use git. The mercurial revision control system is much easier to learn and use, and can push to github (using remote git extension).


I would recommend using a revision-control system (but not git). According to the Software Engineering Institute's Capability Maturity Model, revision-control is the first think you need to adopt to get for ad-hoc to repeatable phase.

2
  • git is a command-line, sorry I misspelled, I meant anything by github.com Mar 14, 2022 at 3:16
  • But I left a small note in the bottom explaining "that I don't understand well git-hub", it still can be a valid answer, but, provide further examples of how it works Mar 14, 2022 at 3:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.