Skip to content

Latest commit

 

History

History
518 lines (325 loc) · 21.9 KB

README.md

File metadata and controls

518 lines (325 loc) · 21.9 KB

${PROJECTNAME}

Version française (French original version)

Official website

Description

${PROJECTNAME} is a fast and lightweight command line static weblog engine which uses the Markdown format for post writting and rendering.

It consists in a homepage, a post list, a tag list and an about's page.

It gives these functionnalities:

  • themes
  • RSS feed
  • keywords on each page (for web ranking)
  • tags
  • static webpages
  • predate posts
  • translations
  • comment system
  • backup
  • publishing scripts to remote servers
  • quick theme creation
  • Nanoblogger posts migration (Cf. Migrate from Nanoblogger section)

Note : ${PROJECTNAME} was not designed to create, edit and delete posts. Even if it offers a script that make new post we suggest you to turn to other projects like Hymby (in development).

Installation

Briefly

In some short steps, here is how to install the last version (current development):

sudo apt-get install lua5.1 lua-filesystem
curl ${GITPROJECT}archive/master.zip
unzip master.zip
cd makefly-master
cp ${PROJECTNAMELOWER}.rc.example ${PROJECTNAMELOWER}.rc
./${PROJECTNAMELOWER} clean && ./${PROJECTNAMELOWER} compile

You should have an action list done on your computer. And result is available in pub directory.

Detailed

If you achieve the Briefly step, go to Use it! section.

Dependencies

Some programs on which ${PROJECTNAME} depends:

  • lua 5.1 and earlier
  • lua-filesystem

So use your distribution package manager to install them. For an example on Debian and derivated, it would be:

apt-get install lua5.1 lua-filesystem

For other distribution, please have a look on your distribution's forum/IRC/community. They will enjoy helping you.

Others methods to install dependancies

If your distribution doesn't have lua-filesystem, you can attempt to install luarocks then install dependancies as:

sudo apt-get install luarocks
luarocks install lua-filesystem

That's all!

Installation

There is 2 ways to install ${PROJECTNAME} on your computer:

So you just have to:

  • fetch the choosen version
  • extract the content in a directory on your computer

And ${PROJECTNAME} is installed.

Configuration

Stable version

No special configuration required. Check that ${PROJECTNAMELOWER}.rc file is present. Otherwise copy ${PROJECTNAMELOWER}.rc.example file or rename it to ${PROJECTNAMELOWER}.rc.

Trunk version

The first time you use ${PROJECTNAME} you don't have any configuration file. An example is available in ${PROJECTNAMELOWER}.rc.example. Copy it to ${PROJECTNAMELOWER}.rc to permit ${PROJECTNAME} to work.

More info

For more information please read The ${PROJECTNAMELOWER}.rc configuration file section.

Use it!

By default the content of the blog is located in the pub directory.

In brief

Some useful commands:

  • ./${PROJECTNAMELOWER} compile: Produce the blog. Available in the pub directory
  • ./${PROJECTNAMELOWER} help: Display available commands
  • ./${PROJECTNAMELOWER} add: Create a post and add its main metadata
  • ./${PROJECTNAMELOWER} clean: Trash the entire final directory content and empty the ${PROJECTNAME}'s cache.

Create content

Create a new post

Use this command:

./${PROJECTNAMELOWER} add

and answer to all given questions. It will generate some files needed by ${PROJECTNAME}.

Note that ${PROJECTNAME} use the markdown format for its posts.

Don't forget to edit the file that the './${PROJECTNAMELOWER} add' command return.

Static content (pictures, videos, PDF files, etc.)

Sometimes you want to share some files as photos, demonstration, shows, etc. static directory exists for this kind of use. Each file that is in this directory will be copied in the result directory.

Example:

  • We created static/makefly.svg file
  • After blog's compilation: pub/makefly.svg file exists

It works for each kind of file in this static directory.

Static pages

Sometimes you'd prefer to add static pages, for an example legal notices.

For this, create pages directory in the ${PROJECTNAME}'s root. Then add some files that contains Markdown content with .md file extension.

Example:

  • We created pages/notices.md file
  • After blog's compilation: pub/mentions.html file exists

This allow you to create a website with static pages.

Note 1: Page result's name will be in lower case and will replace spaces with underscore (_ char).

Note 2: No dynamic link will be make to static page. You will need to modify template yourself to include a link to the static page. Cf. Template ' structure section.

To learn more about static page I invite you to read documentation about static pages creation

The 'special' directory

This one is named special because it can contain some file you have to create in order to activate a functionality:

  • about.md : Is the content of an about's page about your website. It will add an item in the website main menu (If your theme support it.)
  • sidebar.md : Add a sidebar on your website. The theme have to support this function.
  • introduction.md : Display this file's content as an introduction on all your website's pages. This could change regarding the choosen theme.
  • footer.md : Display this file's content as a footer on all your website's pages. This could change regarding the choosen theme.

Produce the blog

After having created ${PROJECTNAMELOWER}.rc (from ${PROJECTNAMELOWER}.rc.example) and having created some posts, just do this:

./${PROJECTNAMELOWER} compile

It will generate a ${PROJECTNAME} weblog to the pub directory (default directory).

Publish result to the web

The result is compatible with all HTML servers. In fact you could probably use result with your website provider. You just have to upload all files from pub directory to your provider's web directory.

From a webserver

If you launch ${PROJECTNAME} on you own server or probably on provider ' server, you should be capable to use install script automation. Just launch it as:

./${PROJECTNAMELOWER} install

...and it will copy all files to ~/public_html directory.

WARNING: This will erase all files from public_html directory!

Note: You can customize the destination by changing ${PROJECTNAMELOWER}.rc file espacially the given line :

INSTALLDIR=${HOME}/public_html

Then relaunch ./${PROJECTNAMELOWER} refresh && ./${PROJECTNAMELOWER} install to recompile and reinstall the weblog.

To a remote computer: publish command

To publish your blog to a remote computer you have to:

  • have an SSH access to the remote machine
  • have rsync program
  • configure PUBLISH_DESTINATION in ${PROJECTNAMELOWER}.rc file
  • launch publish command

That's all!

Note that PUBLISH_DESTINATION looks like:

[email protected]:/myhomedirectory/public_dir

Once having complete this variable in ${PROJECTNAMELOWER}.rc file, just launch:

./${PROJECTNAMELOWER} publish

For developers: You can also edit tools/publish.sh file and change script content to you own code.

Create a new theme

To make easier the theme creation you can use this command:

./${PROJECTNAMELOWER} theme myTheme

where myTheme is to replace by your own theme name.

Note: This exploits a theme called Base as example.

For template designer have a look here: Themes documentation.

Translation

A simple way to translate ${PROJECTNAME} to your language is to copy the lang/translate.en file to another translation file. For an example, for french (with fr code), you can copy lang/translate.en to lang/translate.fr and change values. Then just change BLOG_LANG option in ${PROJECTNAMELOWER}.rc file.

Backup

Perhaps would you backup some important files in ${PROJECTNAME}? It's possible via backup command. Just launch it like this:

./${PROJECTNAMELOWER} backup

Requirements:

  • tar
  • gzip

Files saved:

  • ${PROJECTNAMELOWER}.rc
  • static directory
  • special directory
  • db directory
  • src directory
  • the directory that contains the choosen theme (for an example templates/default/)

Result: This will create a tarball named YYYYmmdd-HM_${PROJECTNAMELOWER}.tar.gz in mbackup directory (for an example 20120823-1732_${PROJECTNAMELOWER}.tar.gz). You can so backup your ${PROJECTNAME} each day for an example.

Tip

You can customize (in your ${PROJECTNAMELOWER}.rc file):

  • the backup directory by using BACKUPDIR option
  • the prefix of the name by using BACKUP_PREFIX option
  • the suffix of the name by using BACKUP_SUFFIX option
  • the date format using BACKUP_FORMAT option

Play with the command line

Knowing that ${PROJECTNAME} works the following way:

./${PROJECTNAMELOWER} help

and use some configuration file as config and ${PROJECTNAMELOWER}.rc, we can play with some variables.

For an example:

LANG=fr_FR.UTF-8 ./${PROJECTNAMELOWER} help

Which permits to change the output language in French.

This way you have the following variables:

  • CURDIR : ${PROJECTNAME} directory path. Permit to launch compilation from another directory. By default the current directory.
  • LANGDIR : directory path that contains translations. By default the lang directory from current path.
  • LANG : language used by the command line. For an example en_US.UTF-8 of fr_FR.UTF-8.
  • CONFIG : default ${PROJECTNAME} configuration file path. By default the config from current directory.
  • RC_CONFIG : user's configuration file path. By default the ${PROJECTNAMELOWER}.rc from current directory.

All these params will permit you to create scripts using ${PROJECTNAME}.

Sources

Sources are available:

Documentation

This file is the documentation. You can read it on github or simply generate an HTML file with this command:

./${PROJECTNAMELOWER} doc

Tips

Write post ahead of current's datetime

In ${PROJECTNAME} you can publish early posts. To do that metadata file should have a timestamp superior to current's one when you generate the weblog.

For an example we are 2013, the 6th march. 12:30:00. The timestamp is : 1362569400. Your post (situated in the db directory) have to have a timestamp inferior to current's one (1362569400).

Delete a post

For a post not to stay on your blog you need to delete two files:

  • post's content in src directory, for an example src/my_post.md
  • post's metadata in db directory, for an example db/1362569400,my_post.mk

Then relaunch blog compilation by using this command:

${PROJECTNAMELOWER} refresh

Change post's date

Post metadata are located in db directory. We take db/1362569400,mon_billet.mk file as an example. Post's date is under a timestamp format. 1362569400 for now. To know the related date, tape the following command:

date -d '@1362569400'

Which gives 2013, Wednesday, March the 6th. 1h30 PM.

Imagine that you would change the date for 2013, March, the 12th. 1h00 PM. To know which timestamp to use, you need to use the following command:

date -d '2013/03/12 13:00:00' +'%s'

Which gives: 1363089600.

We just have to move the metadata file with the following command:

mv db/1362569400,my_post.mk db/1363089600,my_post.mk

Nothing else.

Write directly the post's content during its creation

Just use the 'content' variable at the beginning of the command:

content="my little content" ./${PROJECTNAMELOWER} add

This will add "my little content" into your new post.

Having a comment system

You can use Isso as comment system.

Once installed and configured, for an example, on mycomment.system.tld, you just have to edit ${PROJECTNAMELOWER}.rc and change these variables:

ISSO = 1
ISSO_URL = mycomment.system.tld

You will so have a comment system on your website.

Note: comments will not be visible on your computer. Only on remote website.

[deprecated] Do not lost comments when migrating from an old domain to a new one

Note: This tip is deprecated since 0.4 ${PROJECTNAME} version as it only works with JSKOMMENT system.

When you migrate from old.domain.tld to new.domain.tld, comments will not appear.

To avoid this problem, just use migratefrom command as:

./${PROJECTNAMELOWER} migratefrom http://old.domain.tld

This will update all your old posts with the old comments' identifier (your old domain) and comments will afressh appear.

The ${PROJECTNAMELOWER}.rc configuration file

Here is some options you can change:

  • BLOG_TITLE: Title of your weblog
  • BLOG_SHORT_DESC: A short description of your weblog
  • BLOG_DESCRIPTION: A long description of your weblog
  • BLOG_LANG: your language code. Note that file lang/translate.YOUR_LANGUAGE_CODE should exists. For an example if I set this parameter to en, a lang/translate.en file should exists!
  • BLOG_CHARSET: your encoding configuration. Should be something like UTF-8 or ISO-8859-1. If you don't know what's this option, just let it to UTF-8.
  • BLOG_URL: absolute URL of your blog. For an example ${PROJECTURL}.
  • BLOG_AUTHOR: Main blog writer. Allow a better indexation in websearch engine.
  • BLOG_COPYRIGHT: Blog copyright. Allow a better indexation in websearch engine.
  • BLOG_KEYWORDS: Keywords that will appears on all webblog pages. Allow a better indexation in websearch engine.
  • RSS_FEED_NAME: Title for the RSS Feed
  • MAX_POST: Max post that would be showed on home page
  • MAX_POST_LINES: Number of lines that should be shown on Homepage. If set to 0 or not referenced in ${PROJECTNAMELOWER}.rc file, then posts are fully shown.
  • MAX_PAGE: Maximum number of post that should be displayed on Post's list. If set to 0 or not used in ${PROJECTNAMELOWER}.rc file, then only one page is done with all posts!
  • DATE_FORMAT: Date format displayed for each post. Please see man date's page for more information.
  • SHORT_DATE_FORMAT: Short date format that would be used on the post list page. Please see man date's page for more information.
  • INDEX_FILENAME: Name given to all index'pages. For an example with INDEX_FILENAME = mainpage, post list page will be named mainpage.html.
  • PAGE_EXT: suffix that all page will have. DO NOT FORGET TO ADD A POINT BEFORE SUFFIX. For an example, with PAGE_EXT = .html, all pages will be under the form: index.html.
  • ABOUT_FILENAME: As described, this is the about's filename. If you set it to "about" for an example, you have to create a "about.md" file into special directory in order to have an about's page. If you change it to "toto", so you have to create a toto.md file into special directory.
  • POSTDIR_NAME: The name you want to be displayed in URL when a user go to post list. For an example, if you set it to "myposts": ${PROJECTURL}myposts/ will display all you posts. This is useful for others languages.
  • TAGDIR_NAME: Same behaviour as POSTDIR_NAME, but for tags. Change it to "mytags" for an example, and you will have URLs like this: ${PROJECTURL}mytags/ to display tag list.
  • THEME: Name of the theme you want to be used. All themes are available in template directory. Each theme have its own directory. For an example, "default" theme have its template/default directory.
  • FLAVOR: This name will be used to select a color from your theme (if exists). For an example in BASE theme you have a stylesheet named color_base_lightblue.css. Set FLAVOR value to lightblue, THEME value to base and recompile : your blog is now blue !
  • BACKUPDIR: Name of directory where backup command will save all files.
  • BACKUP_FORMAT: Date format that would be used for the backup file.
  • BACKUP_PREFIX: prefix used for the backup file between the date and the filename.
  • BACKUP_SUFFIX: suffix used for the backup file between the filename and the extension.
  • SIDEBAR_FILENAME: As described, name of sidebar file that would be used to create a sidebar. If you set it to "sidebar" for an example, you have to create a "sidebar.md" file into special directory in order to have this sidebar. Note that your theme should support sidebars!
  • SIDEBAR: If set to 1, so activate a sidebar on ${PROJECTNAME}. Note that your theme should support sidebars!
  • PUBLISH_DESTINATION: Full address from where to send files in order to publish them.
  • PUBLISH_SCRIPT_NAME: script filename used to send files from pub directory to a destination filled in PUBLISH_DESTINATION variable.
  • SEARCH_BAR: If set to 1, activate a search bar on ${PROJECTNAME}. Note that your theme should support search bar!
  • MAX_RSS: Max RSS posts that would be fetch from your users.
  • ISSO : If set to 1, this activate a comment system on ${PROJECTNAME}. Note that your theme should support comment system. Warning: default server is mycomment.system.tld which doesn't work as you should install yours. More info are available on isso project installation page.
  • ISSO_URL (optional): Define a ISSO server on which send comments. For example mycomment.system.tld. Warning: don't use http:// behind the address. It permits to keep to have http or https when needed.
  • ISSO_MAX (optional): Define a limit for displayed comments for ISSO comment system. By default 3.
  • ELI_USER: If set, this activates a badge for StatusNet/GNU Social network. Note that your theme should support ELI widget. By default this functionality use StatusNet/GNU Social's API.
  • ELI_TYPE (optional): Change this to "group" to follow a group instead of a user on StatusNet/GNU Social. By default "user".
  • ELI_MAX (optional): Permit to choose how many statuses to display. On StatusNet/GNU Social, this couldn't bypass the default 20 items. Default value: 5.
  • ELI_API : Your StatusNet URL. For an example: "https://quitter.se/".
  • INSTALLDIR : Permit to choose a target directory when using ./${PROJECTNAMELOWER} install command (Read more in Publish result to the web chapter)
  • SORT (optional) : Sort posts' list. Use ASC for posts to be from the oldiest to the latest. DESC (default value) sort posts from the latest to the oldiest.
  • AUTO_EDIT (optionnel) : Allow to edit automatically posts after their creation. Use the EDITOR variable content to know which editor to use.
  • SH : If set, this activates syntax highlighting for code using:
    
    
    man man

Migrate from Nanoblogger

A script that permits to migrate from Nanoblogger exists: nb2makefly.

I guest you to read the nb2makefly documentation to know more about it.

The project

Description

${PROJECTNAME} is a quick and simple alternative of Nanoblogger.

Red alert, bug detected!

You find a bug? Or something goes wrong? Let's go opening a ticket on Github. It's simple:

  • Go to this link
  • If you're not registered, use Sign up link. Then reclick on the previous link and continue to do steps
  • Click on New Issue
  • Give a title that could be a short description of your problem
  • Then under title, explain in details:
    • What you do
    • What you have after that
    • What you expect
    • [optional] give the copy/paste of what you see on your computer or give some screenshots
  • Validate by using Submit new issue

This take few minutes and permit to improve ${PROJECTNAME}. Thanks -in advance - a lot for your help!

Development

${PROJECTNAME} is developed in Lua, CSS and HTML.

The code of the software is available in the given repository:

Tip to fork the project

The project can be duplicated and renamed easily. For that just use the given variable in ${PROJECTNAMELOWER} file:

  • PROJECTNAME
  • PROJECTURL
  • GITPROJECT

Then rename the ${PROJECTNAMELOWER} file to the name given in PROJECTNAME variable, in lower case.

I suggest you to rename the ${PROJECTNAMELOWER}.svg file to those given in PROJECTNAME..

Good fork and good luck!

Docker file

A Docker file is available to test ${PROJECTNAME}: https://registry.hub.docker.com/u/bl4n/docker-makefly/

Contact

You can contact me to this address.

License

This software is published under GNU Affero General Public License 3.0.

Stats

Some stats about project could be found on Ohloh.net.