What is Reddit's opinion of
MkDocs?
From 3.5 billion Reddit comments
23 reviews of this app found across Reddit:
I find that restructured text is overkill for almost everything I do. I get frustrated when I have to lookup too much arcane syntax, and I'm just trying to write pretty simple things like READMEs and some narrative documentation. Markdown and MkDocs does the trick.
If you do really think the current style is a problem feel free to raise it on the discussion group to see what others think - we use MkDocs, so it'd be easy enough to change the theme to eg. the built-in mkdocs style... http://www.mkdocs.org/
You shouldn't be looking for an "editor" that does this. What you want is a website generator or documentation generator. Something like:
Note I have no experience with those suggestions (well, I've used Jekyll before). I'd also suggest considering whether using something based on reStructuredText or AsciiDoc might not be better long-term, since they tend to be more consistent than the poorly-defined Markdown.
I personally use Mkdocs. It's dead simple to publish (just a git push). You'll get a free github.io domain with your repo with a full website for your project.
You should check out MKDocs we use it for our actual documentation but it'd work just as well for personal docs!
You don't even need to compile it to html most of the time, if you do you can just do mkdocs serve and hit up localhost in your browser and have it all pretty and rendered.
> Concerning FTP – I know, that's just the way things are done here (using sftp).
SFTP's fine, as long as you're not using plain old FTP.
> where I can simply edit pages/info etc.. I don't want it in the codebase, or generated via comments etc.. I also have a designer with no coding skills that needs to access/edit this information sometimes, I just want a simple solution.
I'm a big fan of mkdocs. You just have folders with Markdown files in them, and when you run mkdocs build, you get a slick and simple site generated (here's an example, that documentation is itself generated with mkdocs). The only markdown you have to explain is that # defines a heading, really, and they can just treat it as plain text otherwise. It doesn't get simpler than text files in a folder -- the hook is that they'd need to use Git to push their edits (you could script this for them) or otherwise have a Dropbox arrangement or something.
If you want it to be a website Dokuwiki might do you. It's in the vein of MediaWiki (like Wikipedia) but stores everything in files, not even a SQLite database.
Looking to get started with HomeLabbing soon. I would check out mkdocs if you like readthedocs. This would let you create a locally hosted documentation site, and is what I plan to use.
I'm surprised nobody has mentioned MkDocs. Simple markdown documentation that renders to very nice online documentation.
I prefer this over things like Confluence because I can keep all the documentation in git, write it in vim, and still have a "pretty" copy for mobile reading.
Sorry about the trouble. May I ask you which OS and mobile browser you are using, or would you mind posting a screenshot or so? I built the documentation with Mkdocs (open source Python documentation builder), and I am sure this would be useful information for debugging the template
EDIT: I have another project, biopandas that's also built with Mkdocs but with a slightly different template. Would you mind checking if the button works there? Just wondering if there's something wrong with the mlxtend template or if it's something else in Mkdocs. I would really appreciate it!
We use MKDocs (converts Markdown into HTML), it lives in our config management repo then when we push something it just builds the site (all static HTML), packages it up, pushes it to the package repo which then gets installed/updated by config management to our "rtfm" server on the next CM run.
The main benefits to this are that you have a fully version controlled wiki which is in lockstep with the infrastructure, you have to enforce a "no docs no code review acceptance" policy but it works for us!
mkdocs is similar and much lighter on resources and installation, if you want it to look similar use the readthedocstheme. Simply pip install and then edit the markdown. I am actually working on a wrapper to allow editing fromt he web as well. It will turn it into a psuedo-wiki style.
I'll relink these static wiki's that use markdown in case you just want to maintain it through an existing checkout system, git, or something. Other suggestions in this thread are pretty good, but +1 for dokuwiki if you're wanting to do it all in the browser.
If you use something like MKDocs even if the server hosting the docs goes down you have all the docs in git, which if you're updating regularly means you have a local copy handy at all times.
I use Jekyll and githubpages for free blog hosting, works really well and is dead simple!
However at work we use mkdocs, we have a docs/ subfolder in our repos which gets built when jenkins does a run, then the files get uploaded to GCS to be served as a static site, really good for having up to date docs that get updated when the code does, assuming you write it but we deal with that by forcing a "no approval without docs" code review process.
JIRA looks really really good. I'm going to see more of the free solutions before I evaluate paid ones. I'll have to see with my superiors whether they'll want to break a buck for JIRA. Also, instead of wiki I'm using MkDocs. Basic theme is kinda boring, but there is material 2 theme which gives it a nice look.
Try (Gutenberg)[https://www.getgutenberg.io/] or (MkDocs)[http://www.mkdocs.org/] maybe?
Otherwise one of the options in (this list)[https://blog.zipboard.co/how-to-start-with-static-sites-807b8ddfecc] may help
This is a pet peeve of mine as well, so I enforce it with mandatory documentation before you can accept a pull request to the config management repo. This does not have to be arduous you can use something like MKDocs and keep the documentation in the same repo, markdown is easy as pie to read in a diff and can be compiled to HTML by mkdocs and slapped on a nginx instance with a git hook.
This does of course mean you have to be doing code reviews, but you really should be doing that anyway IMHO.
I am going to be using mkdocs with an admin page I wrote in flask. If interested in beta testing let me know, it should be on GitHub later today.
I also was looking into MoinMoin but it doesn't exactly fit easy to navigate. If you use ansible I have a handy playbook you can use for a quick deploy to test.
If you're a linux shop and use config management we've found using MKDocs and storing it in the same repo as you config management is awesome.
Your documentation is fully versioned and completely inline with your CM code, combine this with code reviews that enforce "no docs = no accept" and having jenkins build the docs, package them up, push the package to your packaging server, then deploy the changes to the documentation server.
Sure it doesn't have web editing but it's markdown and I'm already in the repo so it's basically effortless, if I could have docstrings in my salt states that'd be even more awesome.
I completely get where you car coming from the environment above is basically what we're running now and the documentation is sparse at best. We're trying to address this by using MKDocs and putting it in the same repo as out Salt states then having a rule of "if your changes don't have documentation your code review doesn't get accepted" but we're really playing catchup at this point with the documentation as it's always the first thing to be dropped when you have zero time.
I guess writing those big all encompassing docs is hard as well, assuming you have the time to just sit down and do it there are so many things to try and capture in a way that makes sense. It's definitely one of the areas I'm lacking and need to work on, you comment has definitely highlighted that and have given be some points to think/work on, cheers random internet stranger!
MkDocs is a simple way to make nice looking pages from markdown. It has integration with GitHub Pages which lets you have a web site associated with every GitHub repository.
It is. mkdocs is primarily geared toward quickly making attractive documentation. There are quite a few web projects it wouldn't work well for, but as far as appearance goes, it's really just bootstrap in this case.
We create our technical documentation (API docs, database info, vps installation info etc.) with MkDocs, which uses Markdown. We just put the docs up for the devs on docs.domain.tld.
For new hire info and business logic I would just use a wiki as you do now, most large companies I worked for did this in a wiki as well.
The only real problem is keeping it up to date, but that's the problem with documentation of any sort in general...