diff --git a/README.org b/README.org index 2991929..0884897 100644 --- a/README.org +++ b/README.org @@ -4,11 +4,17 @@ This package will be an org exporter backend that exports =org-mode= to =markdow What this package is planned to do -- -- Write blog posts in =org-mode=. +- Write blog posts and other content in =org-mode=. - For *current subtree* - Export the org-mode meta-data and content into a separate markdown file. - Do that with each save. + +At present this project consists of the following files: + +- =ox-blackfriday.el=: a derived backend that exports to the blackfriday markdown syntax, which Hugo uses as a basis +- =ox-hugo-helper.el=: collection of legacy functions gleaned from the web + This package might evolve into a multi-.el project. 1. An =ox-hugo.el= that just deals with exporting org to md. @@ -19,8 +25,9 @@ This package might evolve into a multi-.el project. - Set separate faces for titles based on /draft/ state and /futureness/. - Option to use template =config.toml= and some default hugo theme. So all a new user would need to do is to (i) have the =hugo= binary in =PATH= (ii) define their =hugo= blog dir in the =defcustom= (iii) =M-x hugo=. -* TODO [0/9] -- [ ] Have =ox-hugo= be a backend derived from =ox-gfm= (=ox-gfm= needed at least for table support). +* TODO [0/12] +- [ ] Have =ox-hugo= be a backend derived from =ox-blackfriday= (=ox-blackfriday= needed at least for table support). +- [ ] fix table horizontal rule generator, which currently adds an additional syntax-breaking space in each cell - [ ] Parse org tags to set the hugo post tags/categories in fm. - [ ] Parse org heading to set the hugo post title in fm. - [ ] Use title to auto-generate file name string. diff --git a/ox-blackfriday.el b/ox-blackfriday.el new file mode 100644 index 0000000..9dc26ce --- /dev/null +++ b/ox-blackfriday.el @@ -0,0 +1,370 @@ +;;; ox-blackfriday.el --- Blackfriday Flavored Markdown Back-End for Org Export Engine + +;; Copyright (C) 2014 Lars Tveito + +;; Author: Lars Tveito, Matt Price +;; Keywords: org, wp, markdown, blackfriday +;; Package-Version: 20170304.1504 + +;; This file is not part of GNU Emacs. + +;; GNU Emacs is free software: you can redistribute it and/or modify +;; it under the terms of the GNU General Public License as published by +;; the Free Software Foundation, either version 3 of the License, or +;; (at your option) any later version. + +;; GNU Emacs is distributed in the hope that it will be useful, +;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;; GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs. If not, see . + +;;; Commentary: + +;; This library implements a Markdown back-end (blackfriday flavor) for Org +;; exporter, based on the `md' back-end. It is mostly copied from Lats Tveito's gfm +;; exporter (https://github.com/larstvei/ox-gfm). + +;;; Code: + +(require 'ox-md) +(require 'ox-publish) + +;;; User-Configurable Variables + +(defgroup org-export-blackfriday nil + "Options specific to Markdown export back-end." + :tag "Org Github Flavored Markdown" + :group 'org-export + :version "24.4" + :package-version '(Org . "8.0")) + + +;;; Define Back-End + +(org-export-define-derived-backend 'blackfriday 'md + :filters-alist '((:filter-parse-tree . org-md-separate-elements)) + :menu-entry + '(?b "Export to Blackfriday Flavored Markdown" + ((?B "To temporary buffer" + (lambda (a s v b) (org-blackfriday-export-as-markdown a s v))) + (?b "To file" (lambda (a s v b) (org-blackfriday-export-to-markdown a s v))) + (?o "To file and open" + (lambda (a s v b) + (if a (org-blackfriday-export-to-markdown t s v) + (org-open-file (org-blackfriday-export-to-markdown nil s v))))))) + :translate-alist '((inner-template . org-blackfriday-inner-template) + (paragraph . org-blackfriday-paragraph) + (strike-through . org-blackfriday-strike-through) + (src-block . org-blackfriday-src-block) + (table-cell . org-blackfriday-table-cell) + (table-row . org-blackfriday-table-row) + (table . org-blackfriday-table))) + + + +;;; Transcode Functions + +;;;; Paragraph + +(defun org-blackfriday-paragraph (paragraph contents info) + "Transcode PARAGRAPH element into Github Flavoured Markdown format. +CONTENTS is the paragraph contents. INFO is a plist used as a +communication channel." + (unless (plist-get info :preserve-breaks) + (setq contents (concat (mapconcat 'identity (split-string contents) " ") "\n"))) + (let ((first-object (car (org-element-contents paragraph)))) + ;; If paragraph starts with a #, protect it. + (if (and (stringp first-object) (string-match "\\`#" first-object)) + (replace-regexp-in-string "\\`#" "\\#" contents nil t) + contents))) + + +;;;; Src Block + +(defun org-blackfriday-src-block (src-block contents info) + "Transcode SRC-BLOCK element into Github Flavored Markdown +format. CONTENTS is nil. INFO is a plist used as a communication +channel." + (let* ((lang (org-element-property :language src-block)) + (code (org-export-format-code-default src-block info)) + (prefix (concat "```" lang "\n")) + (suffix "```")) + (concat prefix code suffix))) + + +;;;; Strike-Through + +(defun org-blackfriday-strike-through (strike-through contents info) + "Transcode STRIKE-THROUGH from Org to Markdown (BLACKFRIDAY). +CONTENTS is the text with strike-through markup. INFO is a plist +holding contextual information." + (format "~~%s~~" contents)) + + +;;;; Table-Common + +(defvar width-cookies nil) +(defvar width-cookies-table nil) + +(defconst blackfriday-table-left-border "") +(defconst blackfriday-table-right-border " ") +(defconst blackfriday-table-separator "| ") + +(defun org-blackfriday-table-col-width (table column info) + "Return width of TABLE at given COLUMN. INFO is a plist used as +communication channel. Width of a column is determined either by +inquerying `width-cookies' in the column, or by the maximum cell with in +the column." + (let ((cookie (when (hash-table-p width-cookies) + (gethash column width-cookies)))) + (if (and (eq table width-cookies-table) + (not (eq nil cookie))) + cookie + (progn + (unless (and (eq table width-cookies-table) + (hash-table-p width-cookies)) + (setq width-cookies (make-hash-table)) + (setq width-cookies-table table)) + (let ((max-width 0) + (specialp (org-export-table-has-special-column-p table))) + (org-element-map + table + 'table-row + (lambda (row) + (setq max-width + (max (length + (org-export-data + (org-element-contents + (elt (if specialp (car (org-element-contents row)) + (org-element-contents row)) + column)) + info)) + max-width))) + info) + (puthash column max-width width-cookies)))))) + + +(defun org-blackfriday-make-hline-builder (table info char) + "Return a function to build horizontal line in TABLE with given +CHAR. INFO is a plist used as a communication channel." + `(lambda (col) + (let ((max-width (max 3 (+ 1 (org-blackfriday-table-col-width table col info))))) + (when (< max-width 1) + (setq max-width 1)) + (make-string max-width ,char)))) + + +;;;; Table-Cell + +(defun org-blackfriday-table-cell (table-cell contents info) + "Transcode TABLE-CELL element from Org into BLACKFRIDAY. CONTENTS is content +of the cell. INFO is a plist used as a communication channel." + (let* ((table (org-export-get-parent-table table-cell)) + (column (cdr (org-export-table-cell-address table-cell info))) + (width (org-blackfriday-table-col-width table column info)) + (left-border (if (org-export-table-cell-starts-colgroup-p table-cell info) "" " ")) + (right-border (if (org-export-table-cell-ends-colgroup-p table-cell info) "" " |")) + (data (or contents ""))) + (setq contents + (concat data + (make-string (max 0 (- width (string-width data))) + ?\s))) + (concat left-border contents right-border))) + + +;;;; Table-Row + +(defun org-blackfriday-table-row (table-row contents info) + "Transcode TABLE-ROW element from Org into BLACKFRIDAY. CONTENTS is cell +contents of TABLE-ROW. INFO is a plist used as a communication +channel." + (let ((table (org-export-get-parent-table table-row))) + (when (and (eq 'rule (org-element-property :type table-row)) + ;; In BLACKFRIDAY, rule is valid only at second row. + (eq 1 (cl-position + table-row + (org-element-map table 'table-row 'identity info)))) + (let* ((table (org-export-get-parent-table table-row)) + (header-p (org-export-table-row-starts-header-p table-row info)) + (build-rule (org-blackfriday-make-hline-builder table info ?-)) + (cols (cdr (org-export-table-dimensions table info)))) + (setq contents + (concat blackfriday-table-left-border + (mapconcat (lambda (col) (funcall build-rule col)) + (number-sequence 0 (- cols 1)) + blackfriday-table-separator) + blackfriday-table-right-border)))) + contents)) + + + +;;;; Table + +(defun org-blackfriday-table (table contents info) + "Transcode TABLE element into Github Flavored Markdown table. +CONTENTS is the contents of the table. INFO is a plist holding +contextual information." + (let* ((rows (org-element-map table 'table-row 'identity info)) + (no-header (or (<= (length rows) 1))) + (cols (cdr (org-export-table-dimensions table info))) + (build-dummy-header + (function + (lambda () + (let ((build-empty-cell (org-blackfriday-make-hline-builder table info ?\s)) + (build-rule (org-blackfriday-make-hline-builder table info ?-)) + (columns (number-sequence 0 (- cols 1)))) + (concat blackfriday-table-left-border + (mapconcat (lambda (col) (funcall build-empty-cell col)) + columns + blackfriday-table-separator) + blackfriday-table-right-border "\n" blackfriday-table-left-border + (mapconcat (lambda (col) (funcall build-rule col)) + columns + blackfriday-table-separator) + blackfriday-table-right-border "\n")))))) + (concat (when no-header (funcall build-dummy-header)) + (replace-regexp-in-string "\n\n" "\n" contents)))) + + +;;;; Table of contents + +(defun org-blackfriday-format-toc (headline) + "Return an appropriate table of contents entry for HEADLINE. INFO is a +plist used as a communication channel." + (let* ((title (org-export-data + (org-export-get-alt-title headline info) info)) + (level (1- (org-element-property :level headline))) + (indent (concat (make-string (* level 2) ? ))) + (anchor (or (org-element-property :CUSTOM_ID headline) + (org-export-get-reference headline info)))) + (concat indent "- [" title "]" "(#" anchor ")"))) + + +;;;; Footnote section + +(defun org-blackfriday-footnote-section (info) + "Format the footnote section. +INFO is a plist used as a communication channel." + (let* ((fn-alist (org-export-collect-footnote-definitions info)) + (fn-alist + (cl-loop for (n type raw) in fn-alist collect + (cons n (org-trim (org-export-data raw info)))))) + (when fn-alist + (format + "## %s\n%s" + "Footnotes" + (format + "\n%s\n" + (mapconcat + (lambda (fn) + (let ((n (car fn)) (def (cdr fn))) + (format + "%s %s\n" + (format + (plist-get info :html-footnote-format) + (org-html--anchor + (format "fn.%d" n) + n + (format " class=\"footnum\" href=\"#fnr.%d\"" n) + info)) + def))) + fn-alist + "\n")))))) + + +;;;; Template + +(defun org-blackfriday-inner-template (contents info) + "Return body of document after converting it to Markdown syntax. +CONTENTS is the transcoded contents string. INFO is a plist +holding export options." + (let* ((depth (plist-get info :with-toc)) + (headlines (and depth (org-export-collect-headlines info depth))) + (toc-string (or (mapconcat 'org-blackfriday-format-toc headlines "\n") "")) + (toc-tail (if headlines "\n\n" ""))) + (org-trim (concat toc-string toc-tail contents "\n" (org-blackfriday-footnote-section info))))) + + + + + +;;; Interactive function + +;;;###autoload +(defun org-blackfriday-export-as-markdown (&optional async subtreep visible-only) + "Export current buffer to a Github Flavored Markdown buffer. + +If narrowing is active in the current buffer, only export its +narrowed part. + +If a region is active, export that region. + +A non-nil optional argument ASYNC means the process should happen +asynchronously. The resulting buffer should be accessible +through the `org-export-stack' interface. + +When optional argument SUBTREEP is non-nil, export the sub-tree +at point, extracting information from the headline properties +first. + +When optional argument VISIBLE-ONLY is non-nil, don't export +contents of hidden elements. + +Export is done in a buffer named \"*Org BLACKFRIDAY Export*\", which will +be displayed when `org-export-show-temporary-export-buffer' is +non-nil." + (interactive) + (org-export-to-buffer 'blackfriday "*Org BLACKFRIDAY Export*" + async subtreep visible-only nil nil (lambda () (text-mode)))) + + +;;;###autoload +(defun org-blackfriday-convert-region-to-md () + "Assume the current region has org-mode syntax, and convert it +to Github Flavored Markdown. This can be used in any buffer. +For example, you can write an itemized list in org-mode syntax in +a Markdown buffer and use this command to convert it." + (interactive) + (org-export-replace-region-by 'blackfriday)) + + +;;;###autoload +(defun org-blackfriday-export-to-markdown (&optional async subtreep visible-only) + "Export current buffer to a Github Flavored Markdown file. + +If narrowing is active in the current buffer, only export its +narrowed part. + +If a region is active, export that region. + +A non-nil optional argument ASYNC means the process should happen +asynchronously. The resulting file should be accessible through +the `org-export-stack' interface. + +When optional argument SUBTREEP is non-nil, export the sub-tree +at point, extracting information from the headline properties +first. + +When optional argument VISIBLE-ONLY is non-nil, don't export +contents of hidden elements. + +Return output file's name." + (interactive) + (let ((outfile (org-export-output-file-name ".md" subtreep))) + (org-export-to-file 'blackfriday outfile async subtreep visible-only))) + +;;;###autoload +(defun org-blackfriday-publish-to-blackfriday (plist filename pub-dir) + "Publish an org file to Markdown. +FILENAME is the filename of the Org file to be published. PLIST +is the property list for the given project. PUB-DIR is the +publishing directory. +Return output file name." + (org-publish-org-to 'blackfriday filename ".md" plist pub-dir)) + +(provide 'ox-blackfriday) + +;;; ox-blackfriday.el ends here