ClojureScript website in org-mode
It’s just a single file, so you can download it and read it right away. But if you want to have the (local) links to work correctly you have to clone some other repositories. See Installation section.
You might be interested in clojure-site-org-mode.
The documentation is in the file ./clojurescript-site.org.
Some links are images in the directory ./assets/. So if you want those links to work correctly it is better to clone the whole project.
Each section in
clojurescript-site.org that corresponds to an asciidoc file in clojurescript-site has a (local) link to this file. So if you want to refer to the original files, you need to clone
To install everything run these following commands:
git clone https://github.com/tonyaldon/clojurescript-site-org-mode.git cd clojurescript-site-org-mode git clone https://github.com/clojure/clojurescript-site.git
Converting clojurescript-site to one org file
I describe here the steps I followed to convert the asciidoc files constituing the ClojureScript documentation into a single org file.
As It was the second time I did it (I did it first with the Clojure documentation -> clojure-site-org-mode), I didn’t have to discovered everything. And so, I tried to make the process more reproducible, more automatic and less manual/interactive (knowing that there is still parts that could/should be automated).
To do the conversion I’ve used:
- interactive modification via
multiple-cursors, keyboard macros,
- manual proofreading and adjustment.
First I cloned
git clone https://github.com/clojure/clojurescript-site.git
01) asciidoc -> docbook -> org
Then I converted all the
asciidoc files of
clojurescript-site into one single org file running the following
for f in `fd --no-ignore .adoc ./clojurescript-site/`; do asciidoctor -b docbook $f -o tmpdocbook ; pandoc --wrap=none -f docbook -t org -o tmporg tmpdocbook ; sed -i -r 's/^[*]+ /*&/g' tmporg ; sed -n "1p" < $f | sed -r "s/^= /* /g" > tmpfile; path_in_content_dir_no_extension=`sed -E 's:.*/content/(.*).adoc:\1:g' <<< $f` ; custom_id=`echo content/$path_in_content_dir_no_extension` ; cljs_page=`echo https://clojurescript.org/$path_in_content_dir_no_extension` ; printf ":PROPERTIES:\n" >> tmpfile ; printf ":CLOJURESCRIPT_SITE_FILE: [[./$f]]\n" >> tmpfile ; printf ":CLOJURESCRIPT_SITE_PAGE: $cljs_page\n" >> tmpfile ; printf ":CLOJURESCRIPT_SITE_AUTHOR: `sed -n "2p" < $f`\n" >> tmpfile ; printf ":CLOJURESCRIPT_SITE_DATE: `sed -n "3p" < $f`\n" >> tmpfile ; printf ":CUSTOM_ID: $custom_id\n" >> tmpfile ; printf ":END:\n" >> tmpfile ; cat tmpfile >> clojurescript-site.org ; cat tmporg >> clojurescript-site.org ; done rm tmpdocbook tmporg tmpfile ;
Let’s break down the previous snippet:
fdto list the
- loop on that list,
asciidoctorto convert each
.adocfile into temporary
pandocto convert each
docbookfile into temporary
- multiple use of
- collect the fontmatter of the
- format the data into
- store it in a temporary file,
- collect the fontmatter of the
- append the temporary files to
At this point, each section of the new created file
clojurescript-site.org corresponds to an
asciidoc file in the ClojureScript documentation.
02) Tree structure
Then I manually made the tree structure:
- I removed the unused sections: “Page Not Found”, “README”, “Search Results”,
- I added the top sections: “About”, “Community”, “Guide”, “News”, “Reference”, “Tools”,
- I added dates to the headlines of the subsection of the “News” section,
- I added the pagination and reordered the section “About”.
I also removed the unused
CUSTOM_ID org properties added by
03) Org list
clojurescript-site.org, I removed empty lines in list that was added by
;; remove empty lines in list (while (re-search-forward "^ *\\(-\\|[1-9]+\\.\\) " nil t) (when (org-match-line (org-item-re)) (save-excursion (forward-line -1) (when (and (org-in-item-p) (= (point-at-bol) (point-at-eol))) (delete-char 1)))))
clojurescript-site.org, I replaced list items with 2 spaces after the dash
- (added by
pandoc), with only one space:
;; replace list with "- " (2 spaces) with "- " (1 space) ;; this step must be done before (hard) wrapping lines (while (re-search-forward "^ *\\(- \\) " nil t) (when (save-match-data (org-match-line (org-item-re))) (let* ((indentation (save-match-data (goto-char (match-beginning 0)) (current-indentation))) (new-indentation (* (/ indentation 3) 2))) (replace-match "\\1" nil nil) (indent-line-to new-indentation))))
04) Source Blocks
clojurescript-site.org, I removed the left padding in every blocks that has been added by
pandoc when converting from
;; remove left padding in org blocks ;; Warning: this loop doesn't take care of line starting by a * ;; after removing the left padding lp which make the line become ;; a headline in org. (while (re-search-forward org-block-regexp nil t) (let ((beg (match-beginning 0)) (end-line (save-excursion (goto-char (match-end 0)) (line-number-at-pos)))) (goto-char beg) (if-let* ((lp (progn (forward-line) (current-indentation))) ((not (zerop lp)))) (while (< (line-number-at-pos) end-line) (unless (= (point-at-bol) (point-at-eol)) (delete-char lp)) (forward-line)))))
05) Wrap lines
I interactively (hard) wrapped the lines at 72 characters.
Then, I replaced inline verbatim markers
= by code markers ~~~ in
;; replace inline code markers = by ~ (while (re-search-forward "=" nil t) (backward-char 1) (if-let ((inline-code (cadr (org-element-code-parser)))) (progn (goto-char (plist-get inline-code :begin)) (delete-char 1) (insert "~") (goto-char (- (plist-get inline-code :end) (plist-get inline-code :post-blank))) (delete-char -1) (insert "~")) (forward-char 1)))
Then, I interactively removed
= verbatim markers when inside links (like this
[[link][=verbatim=]]). Org markers don’t nest inside org links. We keep the links because they are more meaningful than the markers.
Then, I interactively replaced nested emphasis markers like this
*set!* as Org emphasis markers don’t nest.
07) Breaklines and escaped character
Then, I interactively removed
\\ breaklines and removed unnecessary use of escaped character
Then I made footnotes unique. As they came from different files in the ClojureScript documentation they were conflicting in
clojurescript-site.org org file. For instance, the footnotes
[fn:1] used to refer to two different footnotes have been renamed uniquely as
Then I converted faq’s questions into headlines.
10) Example block and source block
Then I replaced org example blocks (
#+BEGIN_EXAMPLE ... #+END_EXAMPLE) with specific source code blocks (
#+BEGIN_SRC ... #+END_SRC) when appropiated:
#+BEGIN_SRC clojure(for Clojure snippets),
#+BEGIN_SRC sh(for command lines snippets),
#+BEGIN_SRC html(for HTML snippets).
12) Internal links and images
I interactively set the internal links using
CUSTOM_ID org property of nodes to be sure to have unicity of links (which might not be the case using headlines content) and anchors in a few cases.
Then I added the
assets directory of Clojure documentation (containing the images) in the project and modified the link to the images.
Copyright © 2015 Rich Hickey and contributors
All documentation contained in this repository is licensed by Rich Hickey under the Eclipse Public License v1.0 unless otherwise noted. To submit a pull request or other contribution, you must sign the Clojure Contributor Agreement.