I started this as an exploration of the web components spec v1... and then I got a bit carried away.
Some could say that there is no need for yet another markdown component or yet another blogging platform. And they would be right. That said, I am trying to make the resulting tool as simple, light, and easy to use as possible:
- Enable end-users to own their own content delivery mechanism.
- Use as little 3rd-party dependencies as possible.
- Decouple your content from the presentation layer, frameworks, or any platform.
- Provide a set of component that allows the easy integration of markdown content into ANY html ANYWHERE.
- Only require the knowledge of markdown, JSON, and html to create complex documentation-based websites such as blogs, documentation, etc.
- Provide SPA (single-page application) functionality without any programming
- Lower level components like
mkdn-storyandmkdn-listcan be used in standalone mode. - Backend integration is provided but is optional and flexible. The backend should be simple enough for simple manual setups... but it should be easy to create intelligent backends that can provide more complex meta-data when there is a lot of content to manage.
- The target use-cases are:
- A blog.
- Online documentation.
- Online fiction
- Create an empty directory with this structure
- Copy all of the mkdn libraries to
/lib - Create/copy markdown content to to
/md - Create an
index.jsonfile that lists the.mdfiles to render - Create an
index.htmlfile that contains your header, footer and anmkdn-view - run a server like
http-serveron the root of the project. For production you will likely need something designed for production express or nginx.
<html lang="en">
<head>
<script src="https://cdn.jsdelivr.net/npm/@webcomponents/[email protected]/webcomponents-loader.js"></script>
</head>
<body>
<h1>My Blog</h1>
<div class="container">
<mkdn-view class="row">
<mkdn-story></mkdn-story>
<mkdn-list></mkdn-list>
<mkdn-store src="/md/index.json" stories="/md/"></mkdn-store>
</mkdn-view>
</div>
<script src="/api/mkdn-story.js"></script>
<script src="/api/mkdn-list.js"></script>
<script src="/api/mkdn-view.js"></script>
</body>
</html>
web-site
|- index.html
|
|- lib
| |- mkdn-view.js
| |- mkdn-story.js
| |- mkdn-list.js
| |- mkdn-nav.js
|
|- md
| |- index.json
| |- md-file-1.md
| |- md-file-2.md
I am implenting this in my free time. A lot is done. But a lot remains to be done too.
- Basic implementation works
- TODO:
- mkdn-story
- add support for dropcaps at document start
- expose some kind of styling interface (in progress)
- document marked and highlight.js integration
- review size of highlight.js... see how to use less
- remove the style property
- mkdn-list
- implement support for groups
- mkdn-view *
- mkdn-store and mkdn-static-store
- document the data formats and back-end api specification (started)
- add caching support
- general
- e2e tests do not work in firefox
- sort out minification and uglification
- create online version of demo (started)
- build and publish
- review decision to have json and markdown transclusion... seems weird practice
- figure out what the magic that webpack is doing!
- events.js should probably be split into smaller files (started)
- mkdn-nav
- finish first implementation
- need a loadFromHash event to reload everything when hash is changed manually
- mkdn-story