1

I came across Docsify (https://docsify.js.org/#/) and have had fun experimenting with it. I'm interested in serving some documentation using my own flask server, instead of Github Pages or with node, however I can't figure out how to implement it.

As described by Docsify (https://docsify.js.org/#/quickstart?id=manual-initialization), locally serving a simpleindex.html to render and README.md as the markdown content works beautifully.

index.html

<!-- index.html -->

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

README.md

# Hi, I'm markdown content

Command line to run the static server (works):

python -m SimpleHTTPServer 3000

Now, in Flask, I am using the app factory + blueprints pattern, and as far as flask is concerned everything works as expected. I can add a new endpoint and it renders just fine. My file structure:

├── instance
│   └── flask.cfg
├── main.py
├── project
│   ├── __init__.py
│   ├── front
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   └── templates
│   │       └── front
│   │           └── index.html
│   ├── documentation
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   └── templates
│   │       └── documentation
│   │           ├── README.md
│   │           └── index.html
│   ├── static
│   │   ├── favicon.ico
│   │   └── style.css
│   └── templates
│       └── base.html
└── requirements.txt

In the project -> documentation -> documentation folder I am adding a README.md at the same level as I did with the above Docsify example that gets served locally so well.

The index.html loads via flask (look carefully and you'll see a sidebar and hamburger menu button), but the markdown content does not and I get '404 - Not found' message. docsify 404

I simply don't know how to implement this, let alone how to do it elegantly.

RancheroBeans
  • 500
  • 1
  • 6
  • 15

2 Answers2

0

here is what i do:

location /doc/ {
    index index.html;
    root /www/api/templates;
}

and then u can access your documention at /doc like mine: enter image description here

and here is my outlook of my site(written by pure html): enter image description here

Haoran Li
  • 1
0

If you serve your index.html at the root of your site (i.e local dev at 3000: localhost:3000/), docsify will try to get all the other files starting from the same level. In your case it expects to find the README.md at this endpoint localhost:3000/README.md.

You could do as follows:

  • create a route in your flask server like /documentation that serves all the files inside the documentation folder. In this way you will get the README.md file at /documentation/README.md
  • add in the docsify config the basePath property (https://docsify.js.org/#/configuration?id=basepath): basePath: '/documentation/'

In this way you should be able to access all your .md files from the route /documentation/* and docsify will successfully renders them.

alcaprar
  • 739
  • 8
  • 18