Org mode, using text files to manage daily

This article is translated from, originally written by Bernt Hansen. Because the original text is long, it will be published in multiple articles. Please mark the source for reprint.
This chapter mainly introduces org Publish export function, org-mode Although it is in text mode, it provides powerful publishing and export function, which is convenient to export to many format documents, including
HTML,LaTex,Markdown Wait.

1. Publish export section

I usually don't do many release related operations on my tasks, but I keep some sensitive customer system information. Most of them are recorded in the form of notes and exported to HTML.

Current All pages of the website are generated by publishing my org file. This contains the index page of the site.

Org mode can publish documents in many formats, including (but not limited to)

  • ASCII (text - not org format file)

  • HTML

  • LaTeX

  • Docbook

    This can be exported to a large number of other formats, such as ODF, XML, etc

  • PDF

    Through LaTex and Docbook

  • iCal

I didn't spend time studying the org mode layout function (making the document more beautiful). For publishing, I mainly use the publishing scenario to create some HTML documents in org mode for online reading. Maybe in the future, I will study the org layout function because of the need.

1.1} new export settings

The new export function is implemented by Nicolas Goazious and released in version 8.0 of org.

My export settings are as follows:

The alphabet option does not work properly until the export settings are loaded.

(setq org-alphabetical-lists t)

;; Explicitly load required exporters
(require 'ox-html)
(require 'ox-latex)
(require 'ox-ascii)

1.1.1 # convert an old exporter into a new exporter

Here are the modifications I made to be compatible with the new exporter function.

  • exporters display dependencies

    • Add ox HTML

    • Add ox latex

    • Add ox ASCII

  • Rename parameter

    • Org export HTML style extra # named org HTML head extra

    • Org export HTML validation link

    • Org export HTML inline images

    • Org export HTML style include default is named org HTML head include default style

    • Org export HTML XML declaration

    • Org export latex lists # named org latex lists

    • Org export HTML style include scripts # named org HTML head include scripts

  • Publish modification

    • Org publish org to HTML # named org HTML publish to HTML

    • org-publish-org-to-org is named org-org-publish-to-org

    • Renaming: Publishing function

    • : style , named: HTML head

  • Modify "BH / is late deadline" to handle the deadline field in the modified agenda

  • Reverse the agenda list according to the deadline

    Negative values will not be displayed in the agenda

  • Add an empty row to prevent it from being exported.

1.2 # org Babel settings

Org Babel enables org files to generate various icons by using external plug-ins, such as ditaa, graphviz, PlantUML and other tools.

The setup is very simple. ditaa # is released following org mode. For other plug-ins, you need to install "graphviz" and "PlantUML" packages in the system.

(setq org-ditaa-jar-path "~/git/org-mode/contrib/scripts/ditaa.jar")
(setq org-plantuml-jar-path "~/java/plantuml.jar")

(add-hook 'org-babel-after-execute-hook 'bh/display-inline-images 'append)

; Make babel results blocks lowercase
(setq org-babel-results-keyword "results")

(defun bh/display-inline-images ()
  (condition-case nil
    (error nil)))

 (quote org-babel-load-languages)
 (quote ((emacs-lisp . t)
         (dot . t)
         (ditaa . t)
         (R . t)
         (python . t)
         (ruby . t)
         (gnuplot . t)
         (clojure . t)
         (sh . t)
         (ledger . t)
         (org . t)
         (plantuml . t)
         (latex . t))))

; Do not prompt to confirm evaluation
; This may be dangerous - make sure you understand the consequences
; of setting this -- see the docstring for details
(setq org-confirm-babel-evaluate nil)

; Use fundamental mode when editing plantuml blocks with C-c '
(add-to-list 'org-src-lang-modes (quote ("plantuml" . fundamental)))

Then you just need to create a "begin SRC" block as the appropriate tool, edit the file, and generate the picture through the shortcut key "C-C-C". Then the structure will be displayed. You can control whether the image is displayed or not through C-C, C-X, c-v.

I prohibit loading images in org files at startup, because when I log in and open org files remotely through ssh, there will be problems if the images are displayed by default (for example, my android phone) and the images cannot be displayed on non-X systems.

It's more important for me to be able to log in and view org files remotely than to view images remotely.

;; Don't enable this because it breaks access to emacs from my Android phone
(setq org-startup-with-inline-images nil)

1.3 # how to use ditta

Ditaa is a tool that can quickly convert ideas into images, and ditaa is released with org mode! All images in this document are automatically generated in plain text through org mode.

Artist mode is convenient to use ditaa to create blocks and connections.

The source code of ditaa drawing in org mode is as follows:

#+begin_src ditaa :file some_filename.png :cmdline -r -s 0.8
  <context of ditaa source goes here>

Here is no #+ begin_src # + end_src # draws an example of a graph.

    +-----------+        +---------+  
    |    PLC    |        |         |                
    |  Network  +<------>+   PLC   +<---=---------+ 
    |    cRED   |        |  c707   |              | 
    +-----------+        +----+----+              | 
                              ^                   | 
                              |                   | 
                              |  +----------------|-----------------+
                              |  |                |                 |
                              v  v                v                 v
      +----------+       +----+--+--+      +-------+---+      +-----+-----+       Windows clients
      |          |       |          |      |           |      |           |      +----+      +----+
      | Database +<----->+  Shared  +<---->+ Executive +<-=-->+ Operator  +<---->|cYEL| . . .|cYEL|
      |   c707   |       |  Memory  |      |   c707    |      | Server    |      |    |      |    |
      +--+----+--+       |{d} cGRE  |      +------+----+      |   c707    |      +----+      +----+
         ^    ^          +----------+             ^           +-------+---+
         |    |                                   |                        
         |    +--------=--------------------------+                    
|                 |                                                         
| Millwide System |            -------- Data ---------                      
| cBLU            |            --=----- Signals ---=--                      


Use viz 1.4

Graphviz is another great tool to facilitate drawing in org documents.

The source code of graphviz drawing in org looks as follows:

#+begin_src dot :file some_filename.png :cmdline -Kdot -Tpng
  <context of graphviz source goes here>
digraph G {
  edge [dir=both]
  plcnet [shape=box, label="PLC Network"]
  subgraph cluster_wrapline {
    label="Wrapline Control System"
    subgraph {
    sharedmem [style=filled, fillcolor=lightgrey, shape=box]
    edge[style=dotted, dir=none]
    exec -> opserver
    exec -> db
    plc -> exec
    edge [style=line, dir=both]
    exec -> sharedmem
    sharedmem -> db
    plc -> sharedmem
    sharedmem -> opserver
  plcnet -> plc [constraint=false]
  millwide [shape=box, label="Millwide System"]
  db -> millwide

  subgraph cluster_opclients {
    label="Operator Clients"
    opserver -> client1
    opserver -> client2
    opserver -> client3

-Kdot , is optional (the default is , dot), but you can replace it with other graphviz (such as , twopi, neato, circo , etc.).

1.5 using PlantUML

I just started using PlantUML, which was created based on Graphviz. I'm still trying to use it. I like it so much so far. The state diagrams in this paper are drawn through plant UML.

The source code of PlantUML drawing in org looks as follows:

#+begin_src plantuml :file somefile.png
  <context of PlantUML source goes here>

1.5.1} sequence diagram

title Example Sequence Diagram
activate Client
Client -> Server: Session Initiation
note right: Client requests new session
activate Server
Client <-- Server: Authorization Request
note left: Server requires authentication
Client -> Server: Authorization Response
note right: Client provides authentication details
Server --> Client: Session Token
note left: Session established
deactivate Server
Client -> Client: Saves token
deactivate Client


1.5.2} use case diagram

LabUser --> (Runs Simulation)
LabUser --> (Analyses Results)


1.5.3 object diagram

Object1 <|-- Object2
Object1 : someVar
Object1 : execute()
Object2 : getState()
Object2 : setState()
Object2 : state

1.5.4} state diagram

[*] --> Start
Start -> State2
State2 -> State3
note right of State3: Notes can be\nattached to states
State2 --> State4
State4 -> Finish
State3 --> Finish
Finish --> [*]


1.6 release of individual documents

Org mode can export the file into a standard format file through an export function. The export function is generally bound to the shortcut key C-c C-e, followed by the shortcut key of the export type to complete the export.

In this way, you can export a single file and a part of the file - if you restrict the org mode file to part of the file, only the selected part will be exported when exporting.

1.7 Release Project

I use the publishing function to export multiple files or projects. I don't want to remember where the export file was generated. The org mode project can solve this problem. This website (other non-public documents) is created through org mode documents and published in the form of projects. For people like me who only configure once and don't pay attention to these details later, this function is very good. I like this way of working (tm)

At present, I have the following five projects, which are published through org mode:

  • norang (website)

  • (website, publishing documents)

  • doc. norang. Ca / private (website, closed file)

  • (test org mode temporary publishing website)

  • org document (org document used by other websites)

Here are my settings:

; experimenting with docbook exports - not finished
(setq org-export-docbook-xsl-fo-proc-command "fop %s %s")
(setq org-export-docbook-xslt-proc-command "xsltproc --output %s /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl %s")
; Inline images in HTML instead of producting links to the image
(setq org-html-inline-images t)
; Do not use sub or superscripts - I currently don't need this functionality in my documents
(setq org-export-with-sub-superscripts nil)
; Use org.css from the norang website for export document stylesheets
(setq org-html-head-extra "<link rel=\"stylesheet\" href=\"\" type=\"text/css\" />")
(setq org-html-head-include-default-style nil)
; Do not generate internal css formatting for HTML exports
(setq org-export-htmlize-output-type (quote css))
; Export with LaTeX fragments
(setq org-export-with-LaTeX-fragments t)
; Increase default number of headings to export
(setq org-export-headline-levels 6)

; List of projects
; norang       -
; doc          -
; org-mode-doc - and associated files
; org          - miscellaneous todo lists for publishing
(setq org-publish-project-alist
      ;  (norang website)
      ; norang-org are the org-files that generate the content
      ; norang-extra are images and css files that need to be included
      ; norang is the top-level project that gets published
      (quote (("norang-org"
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :recursive t
               :table-of-contents nil
               :base-extension "org"
               :publishing-function org-html-publish-to-html
               :style-include-default nil
               :section-numbers nil
               :table-of-contents nil
               :html-head "<link rel=\"stylesheet\" href=\"norang.css\" type=\"text/css\" />"
               :author-info nil
               :creator-info nil)
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive t
               :author nil)
               :components ("norang-org" "norang-extra"))
              ;  (norang website)
              ; doc-org are the org-files that generate the content
              ; doc-extra are images and css files that need to be included
              ; doc is the top-level project that gets published
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :recursive nil
               :section-numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function (org-html-publish-to-html org-org-publish-to-org)
               :style-include-default nil
               :html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
               :author-info nil
               :creator-info nil)
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive nil
               :author nil)
               :components ("doc-org" "doc-extra"))
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :recursive nil
               :section-numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function (org-html-publish-to-html org-org-publish-to-org)
               :style-include-default nil
               :html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
               :auto-sitemap t
               :sitemap-filename "index.html"
               :sitemap-title "Norang Private Documents"
               :sitemap-style "tree"
               :author-info nil
               :creator-info nil)
               :base-directory "~/git/"
               :publishing-directory "/ssh:www-data@www:~/"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive nil
               :author nil)
               :components ("doc-private-org" "doc-private-extra"))
              ; Miscellaneous pages for other websites
              ; org are the org-files that generate the content
               :base-directory "~/git/org/"
               :publishing-directory "/ssh:www-data@www:~/org"
               :recursive t
               :section-numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function org-html-publish-to-html
               :style-include-default nil
               :html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
               :author-info nil
               :creator-info nil)
              ;  (norang website)
              ; org-mode-doc-org this document
              ; org-mode-doc-extra are images and css files that need to be included
              ; org-mode-doc is the top-level project that gets published
              ; This uses the same target directory as the 'doc' project
               :base-directory "~/git/org-mode-doc/"
               :publishing-directory "/ssh:www-data@www:~/"
               :recursive t
               :section-numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function (org-html-publish-to-html)
               :plain-source t
               :htmlized-source t
               :style-include-default nil
               :html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
               :author-info nil
               :creator-info nil)
               :base-directory "~/git/org-mode-doc/"
               :publishing-directory "/ssh:www-data@www:~/"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif\\|org"
               :publishing-function org-publish-attachment
               :recursive t
               :author nil)
               :components ("org-mode-doc-org" "org-mode-doc-extra"))
              ;  (norang website)
              ; org-mode-doc-org this document
              ; org-mode-doc-extra are images and css files that need to be included
              ; org-mode-doc is the top-level project that gets published
              ; This uses the same target directory as the 'doc' project
               :base-directory "/tmp/publish/"
               :publishing-directory "/ssh:www-data@www:~/"
               :recursive t
               :section-numbers nil
               :table-of-contents nil
               :base-extension "org"
               :publishing-function (org-html-publish-to-html org-org-publish-to-org)
               :html-head "<link rel=\"stylesheet\" href=\"\" type=\"text/css\" />"
               :plain-source t
               :htmlized-source t
               :style-include-default nil
               :auto-sitemap t
               :sitemap-filename "index.html"
               :sitemap-title "Test Publishing Area"
               :sitemap-style "tree"
               :author-info t
               :creator-info t)
               :base-directory "/tmp/publish/"
               :publishing-directory "/ssh:www-data@www:~/"
               :base-extension "css\\|pdf\\|png\\|jpg\\|gif"
               :publishing-function org-publish-attachment
               :recursive t
               :author nil)
               :components ("tmp-org" "tmp-extra")))))
; I'm lazy and don't want to remember the name of the project to publish when I modify
; a file that is part of a project.  So this function saves the file, and publishes
; the project that includes this file
; It's bound to C-S-F12 so I just edit and hit C-S-F12 when I'm done and move on to the next thing
(defun bh/save-then-publish (&optional force)
  (interactive "P")
  (let ((org-html-head-extra)
        (org-html-validation-link "<a href=\"\">Validate XHTML 1.0</a>"))
    (org-publish-current-project force)))

(global-set-key (kbd "C-s-<f12>") 'bh/save-then-publish)

The main projects are norang, Doc, Doc private, org mode doc and tmp. These items are automatically published to the corresponding directory of the web server. When publishing, all modified pages will be exported, pictures will be generated and corresponding files will be copied to the web server, so it is convenient to view immediately.

Website Contains all customer private documents (so you need to configure access rights). Access rights are realized through Apache access rights control. I will not create these document links (to access them) from public pages. It will be displayed in the path ~ / git / doc norang. Ca / someclient / all org file indexes if the site is set to be visible. I will use most of the information on these websites. Of course, if my customers are interested in this information, I will also give them permission to view it.

It's great. I know my notes are on the website and I can visit them. It's also convenient for me to share notes with others. Just give them corresponding links (and open access rights).

All I need to remember is to modify the appropriate org file and publish it through C-S-F12 - not particularly difficult:)

I have a temporary publishing site to verify the published project. This is the "tmp" website. It copies the / tmp/publish "files and exports them to the publishing path. This facilitates online testing of some new features.

1.8 other export settings

These are the setup scripts I collected about exporting and publishing.

1.8.1 # reinforcement source code Latex lists

When exporting to latex format, I use the following settings to consolidate the source list:

(setq org-latex-listings t)

1.8.2 # exporting HTML without XML header

I use the following settings to remove XML headers from HTML exported documents. If you do not remove these XML headers, convert them to ODT when you open HTML through open Office.

(setq org-html-xml-declaration (quote (("html" . "")
                                       ("was-html" . "<?xml version=\"1.0\" encoding=\"%s\"?>")
                                       ("php" . "<?php echo \"<?xml version=\\\"1.0\\\" encoding=\\\"%s\\\" ?>\"; ?>"))))

1.8.3} binding parameter export is allowed during export

The following settings allow setting # + BIND: in this way, some parameters can be bound during export, and there is no need to confirm again during export. In rare cases, I will override some org mode export parameters. In this way, the prompt will not pop up when exporting.

(setq org-export-allow-BIND t)


Keywords: html plugin emacs lisp

Added by realnsleo on Mon, 14 Feb 2022 03:02:16 +0200