mdsh - a static site generator

[sc0ttman]

mdsh

A static site generator, which produces a simple blog.
It can also easily produce custom pages.

The name mdsh refers to the custom Markdown + Shell format used to write blog posts (you can also use HTML).

* Homepage: https://sc0ttj.github.io/mdsh/about.html
* Demo blog here: https://sc0ttj.github.io/mdsh/
* Wiki: https://github.com/sc0ttj/mdsh/wiki
* Github repo: https://github.com/sc0ttj/mdsh

Requirements:

- Bash
- Perl (for markdown.pl)
Optional:
- Git and a GitHub account (if you want super easy deployment and free hosting at GitHub Pages)

Features

• * Written in Bash shell script
  * Easy setup - just clone the repo, edit the .site_config file.
  * Use a mix of Markdown and shell code to write blog posts!
  * Use your terminal - no text editor or IDE required.
  * Builds a fast blog with great SEO and mobile support
  * Automatically generates index and listings pages for categories, tags, and more.
  * Can generate a valid RSS feed and XML sitemap!
  * Includes a "Contact" page that works out of the box! (uses formspree.io to send you emails)
  * Includes blazing fast site/page search (uses Jets, requires JavaScript)
  * Supports fullscreen, native app experience on mobile/smartphone if added to Homescreen
  * Optionally use Google Fonts to choose custom web fonts
  * Optionally use Unpkg.com to manage JavaScript libraries/dependencies
  * Optionally use Git for saving, managing and reverting versions and deployments
  * Optionally use GitHub Pages for free, fast, and secure (SSL enabled) site hosting
  * Support many other web hosting options too

Usage

• * Clone the repo:

  Code: Select all

  git clone https://github.com/sc0ttj/mdsh blog

  * Enter project dir:

  Code: Select all

  cd blog

  * Use GitHub Pages for hosting:

  Code: Select all

  git checkout -b gh-pages

  * Edit site settings:

  Code: Select all

  $EDITOR .site_config

  * Build homepage:

  Code: Select all

  rebuild homepage

  * Create your first post (just follow the on-screen instructions): .

  Code: Select all

  new post

  
  ^ after you create a post, all site index pages and menus will be rebuilt.
  
  * To re-build all pages:

  Code: Select all

  rebuild -all

  * To publish:

  Code: Select all

  publish "some version or message"

NOTES:

If you dont want to use Git or GitHub, you can just FTP the HTML files and 'assets' dir somewhere instead.

[sc0ttman]

I've done lots of improvements to this:

Now it can also auto-generate:

- contact form (emails you, has spam protection)
- RSS feed
- XML sitemap
- better homepage (listing blog posts in full)
- better site meta info
- post counts for authors, tags and categories
- more page index types: yearly and monthly (Examples: /posts/2019/index.html and /posts/2019/02/index.html)

Plus some features:
- built-in site search (requires JS, uses Jets - a fast page filtering thingy)

Plus some fixes:

- better support for web hosting on GitLab Pages and Netlify
- fixes in CSS (page styling)
- better mobile/small screen support

Still to do:

- see Issues page on Github, but here is a summary:
- enable comments on posts using either Disqus or Gitment (user chooses)
- enable easy setup of GitHub/GitLab/Netflify hosting (user chooses) - github DONE
- add easy wasy to start a local webserver (with correct settings, paths, etc) - DONE
- add JS things like lazy loading images, other "nice to haves" (mainly JS based performance enhancers)
- a non-JS fallback site search (Google Custom Search Engine or something)
- finish documentation

[sc0ttman]

Recent updates, just FYI:

- code highlighting at build time (no JS required by visitors browser!)
- re-written to use mustache templates
- created a full site navigation template
- added the template above the site footer
- many, many bug fixes for SEO stuff, meta info, JSON-LD, etc
- much easier installation and usage
- to setup, run `source .site_config`, then `help`

It is now made with templates, so customising the layouts of your site is possible.

This static site generator will eventually be quite powerful: able to output sites as HTML, AMP, AppleNews (json) and FBIA (facebook instant articles).. It currently does HTML (and some JSON-LD).

It already has excellent SEO, having 100% valid HTML, CSS and JSON-LD (linked data).. It is compatible with 'enhanced search results' in Google pages (carousels, breadcrumbs, site search boxes, etc).

It also has all the `og:graph` stuff needed to share pages properly, or page sections, on social media - with all the right meta info, headings, title photo, etc.

It has great performance: the demo website score is 99/100 (mobile) and 100/100 (desktop) on Googles PageSpeed insights, and score very highly in almost all WebPageTest tests (the ones it doesn't score well on - caching - are simply due to the GitHub hosting I am using for the demo blog).

Sites generated work perfect on phones/tablets etc, and are "mobile-first" - designed primarily for mobile, with enhanced experience for desktop/larger screens - as it should be these days.

There are various built-in index pages (categories, tags, authors), which look boring at the moment, as they're simple lists, but soon enough, the lists will be nice grids - with each post having a title, img, descr, etc..

Other built-in page include an archive page, contact page, site search page, RSS feed, XML sitemap and more.

The non-JavaScript experience is 99% the same as the full experience, except the site search won't work - I will add a no JS fallback soon.

But complex JS apps/pages are possible in mdsh too - cos it is super easy to add NPM packages as JS deps to each page (or defaults deps for all pages), using Unpkg.com - You simply provide a comma separated list of NPM package names when creating the page..

You can also add your own custom JS scripts to pages easily, by putting JS files in assets/js/ which match the page they're for.. (example: my-page.html needs assets/js/my-page.js)

I work as a day job in web dev these days, so put some of that knowledge to use here - good accessiblilty, good performance, good browser support.

Compared to other lightweight blog things (like Bashblog , pplog, shellCMS, etc), I guarantee you the HTML/CSS etc in `mdsh` sites is far better, far more future proofed, more standards compliant, more SEO friendly, more social media friendly and more phone/mobile-friendly, better accessibility (for visually impaired users), all while maintaining great old browser support.

[sc0ttman]

Just an update:

Mdsh is now capable of building web applications or local system tools with web-based frontends, using a range of different languages (Bash, PHP, Python, etc).

https://sc0ttj.github.io/mdsh/posts/201 ... uages.html

Also, there has been reliability fixes: https://sc0ttj.github.io/mdsh/posts/201 ... kdown.html

Plus other new features:

- easily truncate posts (post excerpts) when previewing them - more info
- improved site navigation

[sc0ttman]

I've added something pretty cool to mdsh (my blog making thing)...

I've implemented Liquid Filters in shell script!

See my blog post: https://sc0ttj.github.io/mdsh/posts/201 ... lters.html

The full list of filters I've implemented exceeds the defaults available in Shopify and even Jekyll.

Here is an example of using these filters in the mustache templates:

Code: Select all

{{#someArray | sort_by 'name' 'asc' | limit 5}}
  Hi {{item.name | titlecase}},
{{/someArray}}

If you just want the filters (which you cna use as a standalone thing), then download this file and source it.

If using the filters standalone, you would use them like so:

Code: Select all

new_array=( $(echo ${someArray[@]} | where 'name' '!=' 'bob') )

Code: Select all

price_in_pounds="$(echo 1000 | money_with_currency £ GBP)"

Code: Select all

summary_text="$(echo "$some_var" | titlecase | truncate_words '..' 20 | strip_html)"

..etc..

[Ananda98]

Hello sc0ttman,

I'm interested with your static site generator. It is similar with another content management system (CMS), e.g. Wordpress?


Sorry for being OOT. Thanks

[sc0ttman]

Hello sc0ttman,

I'm interested with your static site generator. It is similar with another content management system (CMS), e.g. Wordpress?


Sorry for being OOT. Thanks

It's more similar to Jekyll.

(because both mdsh and Jekyll generate HTML pages from Markdown files, and both use YAML files and a templating system to add allow custom data and layouts (if you need them)..

But mdsh is way simpler than either Wordpress or Jekyll, although I am not that far away from implementing a plugin system.

The site generated by mdsh is more lightweight and simple than a blog generated by Wordpress..

But yes, it is a CMS type thing that lets you run a blog.

The main difference (from an end-user perspective) with Wordpress is that

- Wordpress has an admin panel interface
- Mdsh uses terminal commands


.. It's in alpha stages right now.. I am currently re-writing some it.. And it is missing some really basic stuff - easy/nice ways to add images, tweets, etc.. Coming soon ...

And hopefully one day I will integrate NetlifyCMS with it, so that it has a similar admin panel to things like Wordpress (so its easier to use for novices)..

[wiak]

What License for mdsh?

I quickly looked for:

"example script by Stéphane Chazelas"

to see the basis but could find it.

Would appreciate a link to that.

Looking forward to trying out mdsh to see how it's functionality compares with Jekyll. I'm also looking around trying to decide what to use for my FirstRib/WeeDog documentation and more.

wiak

[wiak]

Is this project still being developed and if so what are the license restrictions to use, if any?

[sc0ttman]

license is "do whatever you want with it"

and yes still being developed .. still "alpha" stages really ... cos it's so slow..

currently working on stealing the custom taxonomies feature from Hugo, and the page "archetypes" as well..

In short, before the changes I'm doing you can create pages or posts, and you get index pages for authors, categories and tags..

After the changes I'm doing, you will be able to create pages of any type you define yourself (not only "page" or "post"), and you will be able to define the taxonomies (like authors, tags, etc) that are associated with each page types..

This will make is easier to create lots of different kinds of content, and to control the auto-generated index/listings pages that they get listed on ..

See here for more info:

About the features: https://github.com/sc0ttj/mdsh/issues/92

The work being done: https://github.com/sc0ttj/mdsh/pull/93