diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 976f302..71c461f 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -587,6 +587,82 @@ Hit =C-x C-s= and be in awe as the browser auto-refreshes to the :EXPORT_FILE_NAME: Contributing Guide :END: #+INCLUDE: "./ox-hugo-manual.org::#note-to-future-contributors" :only-contents t +** Image Links :wiki: +:PROPERTIES: +:EXPORT_TITLE: +:EXPORT_FILE_NAME: Image Links +:END: +For the sake of the below explanation, let's have the /HUGO_BASE_DIR/ +(the directory containing the Hugo site's =config.toml= file) be +=~/hugo/=. + +In that case, the Hugo /static/ directory will be =~/hugo/static/=. +*** References to files in the /static/ directory +Now if you have a file =~/hugo/static/images/foo.png=, =ox-hugo= makes +it convenient for you to reference that image by simply +=/images/foo.png=. *This is the default behavior of other Org +exporters.* But in the case of Hugo, as the referenced file will +normally be in the Hugo /static/ directory, the =/images/foo.png= +style of short reference is allowed *if* that is a valid path under +the /static/ directory. + +See the below examples on how to reference images in different ways: +**** Inline image (Unhyperlinked) +#+BEGIN_SRC org +[[/images/foo.png]] +#+END_SRC +**** Inline image (Hyperlinked to the image itself) +#+BEGIN_SRC org +[[file:/images/foo.png][file:/images/foo.png]] +#+END_SRC +- NOTE :: The =file:= prefix *has to be used* in both Link and + Description components of the Org link. + +- NOTE-2 :: GitHub Wiki screws up the above code block. It actually + looks like below but *without* the space in-between =]= + and =[=. + #+BEGIN_SRC org + [[file:/images/foo.png] [file:/images/foo.png]] + #+END_SRC +**** Link to an image (Image not inlined) +#+BEGIN_SRC org +[[/images/foo.png][Click here to see foo.png]] +#+END_SRC +This applies to references to non-image files in the /static/ +directory too. +*** Having references to files *outside* the /static/ directory +This is a unique feature of =ox-hugo=. + +If a reference is made to a file outside the Hugo /static/ directory +and if it has one of these extensions: ="jpg"=, ="jpeg"=, ="tiff"=, +="png"=, ="pdf"=, ="odt"= , then that file is copied by =ox-hugo= to +the /static/ directory. + +Here is an example link: +#+BEGIN_SRC org +[[../files-to-be-copied-to-static/static/images/copy-of-unicorn-logo.png]] +#+END_SRC + +*Note*: If you link to files outside of the Hugo =static= directory, +just ensure that that path contains =/static/= if you would like to +preserve the directory structure. /The necessary directories are also +created inside the /static/ directory to preserve the structure./ + +Example translations between outside =static= directory paths to the +copied location inside =static=: +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| +| File location outside =static= | Copied-to location inside =static= | Explanation | +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| +| =~/temp/static/images/foo.png= | =/static/images/foo.png= | If the *outside* path has =/static/= in it, the directory structure after that is preserved when copied. | +| =~/temp/static/img/foo.png= | =/static/img/foo.png= | (same as above) | +| =~/temp/static/foo.png= | =/static/foo.png= | (same as above) | +| =~/temp/static/articles/zoo.pdf= | =/static/articles/zoo.pdf= | (same as above) | +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| +| =~/temp/bar/baz/foo.png= | =/static/foo.png= | Here, as the *outside* path does not have =/static/=, the file is copied directly into the Hugo =static/= directory. | +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| + +See the [[https://github.com/kaushalmodi/ox-hugo/wiki/Usage#before-you-export][Usage → Before you export Wiki section]] to learn how to +set the *HUGO_BASE_DIR*. * COMMENT Local Variables :ARCHIVE: # Local Variables: # fill-column: 70 diff --git a/doc/ox-hugo.wiki b/doc/ox-hugo.wiki index 4442d4b..58f8f11 160000 --- a/doc/ox-hugo.wiki +++ b/doc/ox-hugo.wiki @@ -1 +1 @@ -Subproject commit 4442d4bd1d90516231b0bf1c8ce7253db89c5bbc +Subproject commit 58f8f118abd5a6494344ec89bd86ee6976b42f44 diff --git a/example-site/content-org/all-posts.org b/example-site/content-org/all-posts.org index eec644b..76fd345 100644 --- a/example-site/content-org/all-posts.org +++ b/example-site/content-org/all-posts.org @@ -88,8 +88,24 @@ inside that div is valid HTML. #+BEGIN_EXPORT md #+END_EXPORT -*** Link to image outside of standard Hugo locations -[[../src-images/copy-of-unicorn-logo.png]] +*** Link to image outside of standard Hugo =static= directory +[[../files-to-be-copied-to-static/static/images/copy-of-unicorn-logo.png]] + +If you link to files outside of the Hugo =static= directory, ensure +that the path contains =/static/= if you would like to preserve the +directory structure. + +Example translations between outside =static= directory paths to the +copied location inside =static=: +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| +| Outside =static= | Copied-to location inside =static= | Explanation | +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| +| =~/temp/static/images/foo.png= | =/static/images/foo.png= | If the *outside* path has =/static/= in it, the directory structure after that is preserved when copied. | +| =~/temp/static/img/foo.png= | =/static/img/foo.png= | (same as above) | +| =~/temp/static/foo.png= | =/static/foo.png= | (same as above) | +| =~/temp/static/articles/zoo.pdf= | =/static/articles/zoo.pdf= | (same as above) | +| =~/temp/bar/baz/foo.png= | =/static/foo.png= | Here, as the *outside* path does not have =/static/=, the file is copied directly into the Hugo =static/= directory. | +|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------| ** Image captions :PROPERTIES: :EXPORT_DATE: 2017-07-19 diff --git a/example-site/content/posts/image-links.md b/example-site/content/posts/image-links.md index 8c01427..701db9d 100644 --- a/example-site/content/posts/image-links.md +++ b/example-site/content/posts/image-links.md @@ -58,6 +58,21 @@ Click below image to jump to the unicorn image. [Discussion](https://github.com/kaushalmodi/ox-hugo/issues/17#issuecomment-313627728) -## Link to image outside of standard Hugo locations {#link-to-image-outside-of-standard-hugo-locations} +## Link to image outside of standard Hugo `static` directory {#link-to-image-outside-of-standard-hugo-static-directory} {{
}} + +If you link to files outside of the Hugo `static` directory, ensure +that the path contains `/static/` if you would like to preserve the +directory structure. + +Example translations between outside `static` directory paths to the +copied location inside `static`: + +Outside `static` | Copied-to location inside `static` | Explanation +---------------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------- +`~/temp/static/images/foo.png` | `/static/images/foo.png` | If the **outside** path has `/static/` in it, the directory structure after that is preserved when copied. +`~/temp/static/img/foo.png` | `/static/img/foo.png` | (same as above) +`~/temp/static/foo.png` | `/static/foo.png` | (same as above) +`~/temp/static/articles/zoo.pdf` | `/static/articles/zoo.pdf` | (same as above) +`~/temp/bar/baz/foo.png` | `/static/foo.png` | Here, as the **outside** path does not have `/static/`, the file is copied directly into the Hugo `static/` directory. diff --git a/example-site/src-images/copy-of-unicorn-logo.png b/example-site/files-to-be-copied-to-static/static/images/copy-of-unicorn-logo.png similarity index 100% rename from example-site/src-images/copy-of-unicorn-logo.png rename to example-site/files-to-be-copied-to-static/static/images/copy-of-unicorn-logo.png diff --git a/ox-hugo.el b/ox-hugo.el index bd8fbdb..1154f35 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -442,7 +442,6 @@ Example value: (org)." (:hugo-level-offset "HUGO_LEVEL_OFFSET" nil 1) (:hugo-section "HUGO_SECTION" nil org-hugo-default-section-directory) (:hugo-base-dir "HUGO_BASE_DIR" nil nil) - (:hugo-static-images "HUGO_STATIC_IMAGES" nil "images") (:hugo-code-fence "HUGO_CODE_FENCE" nil t) (:hugo-menu "HUGO_MENU" nil nil) (:hugo-menu-override "HUGO_MENU_OVERRIDE" nil nil) @@ -707,7 +706,6 @@ and rewrite link paths to make blogging more seamless." (concat (file-name-sans-extension raw-path) ".md") raw-path))) (raw-path (org-element-property :path link)) - (images-dir (org-string-nw-p (plist-get info :hugo-static-images))) (type (org-element-property :type link))) ;; (message "[ox-hugo-link DBG] link filename: %s" (expand-file-name (plist-get (car (cdr link)) :path))) ;; (message "[ox-hugo-link DBG] link type: %s" type) @@ -752,14 +750,9 @@ and rewrite link paths to make blogging more seamless." (org-export-get-reference destination info)))))))) ((org-export-inline-image-p link org-html-inline-image-rules) ;; (message "[org-hugo-link DBG] processing an image: %s" contents) - (let* ((path (org-hugo--attachment-rewrite - (if (file-name-absolute-p raw-path) - (expand-file-name raw-path) - raw-path) - info)) + (let* ((path (org-hugo--attachment-rewrite-maybe raw-path info)) (caption (org-export-data - (org-export-get-caption - (org-export-get-parent-element link)) + (org-export-get-caption (org-export-get-parent-element link)) info)) (parent (org-export-get-parent link)) (attr (org-export-read-attribute :attr_html parent)) @@ -782,49 +775,73 @@ and rewrite link paths to make blogging more seamless." (let ((path (cond ((member type '("http" "https" "ftp")) (concat type ":" raw-path)) - ((and (string= type "file") - (or (null images-dir) - ;; Do not add the "file://" prefix if the - ;; raw-path begins with the HUGO_STATIC_IMAGES - ;; dir name. - (not (string-match-p (concat "\\`/" images-dir "/") raw-path)))) - (org-hugo--attachment-rewrite - (org-export-file-uri - (funcall link-org-files-as-md raw-path)) - info)) + (;; Do not add the "file://" prefix if the raw-path + ;; is in the Hugo "static" dir. + (and (string= type "file") + (let ((static-dir (file-truename + (concat + (file-name-as-directory (plist-get info :hugo-base-dir)) + "static/"))) + (raw-path-true (file-truename raw-path))) + (string-match-p (regexp-quote static-dir) raw-path-true))) + (let* ((path1 (org-export-file-uri (funcall link-org-files-as-md raw-path))) + (path1 (replace-regexp-in-string "\\`file://" "" path1))) + (org-hugo--attachment-rewrite-maybe path1 info))) (t raw-path)))) (if contents - (format "[%s](%s)" contents path) + (progn + ;; (message "[ox-hugo DBG org-hugo-link: contents=%s path=%s" contents path) + (format "[%s](%s)" contents path)) (format "<%s>" path))))))) ;;;;; Helpers -(defun org-hugo--attachment-rewrite (path info) - "Copy local images and pdfs to the \"static/\" directory. +(defun org-hugo--attachment-rewrite-maybe (path info) + "Copy local images and pdfs to the \"static/\" directory if needed. Also rewrite image links. -PATH is the path to the image or pdf attachment. +PATH is the path to the image or pdf attachment. If the PATH +already exists in the Hugo \"static\" directory, just return the PATH. + INFO is a plist used as a communication channel." - ;; (message "[ox-hugo attachment DBG] The Hugo images dir is: %s" (plist-get info :hugo-static-images)) ;; (message "[ox-hugo attachment DBG] The Hugo section is: %s" (plist-get info :hugo-section)) ;; (message "[ox-hugo attachment DBG] The Hugo base dir is: %s" (plist-get info :hugo-base-dir)) - (let* ((full-path (file-truename path)) - (exportables '("jpg" "jpeg" "tiff" "png" "pdf" "odt" )) - (file-name (file-name-nondirectory path)) - (image-export-dir (concat - (file-name-as-directory (plist-get info :hugo-base-dir)) - "static/" - (file-name-as-directory (plist-get info :hugo-static-images)) - )) - (exported-image (concat image-export-dir file-name))) - ;; (message "[ox-hugo DBG] Image export dir is: %s" image-export-dir) - (if (and (file-exists-p full-path) + (let* ((path-true (file-truename path)) + (exportables '("jpg" "jpeg" "tiff" "png" "pdf" "odt")) + (static-dir (file-truename + (concat + (file-name-as-directory (plist-get info :hugo-base-dir)) + "static/")))) + ;; (message "[ox-hugo DBG attch rewrite] Image export dir is: %s" static-dir) + ;; (message "[ox-hugo DBG attch rewrite] path: %s" path) + ;; (message "[ox-hugo DBG attch rewrite] path-true: %s" path-true) + (if (and (file-exists-p path-true) (member (file-name-extension path) exportables) - (file-directory-p image-export-dir)) + (file-directory-p static-dir)) (progn - (unless (file-exists-p exported-image) - (copy-file full-path exported-image)) - (concat "/" (file-name-as-directory (plist-get info :hugo-static-images)) file-name)) + ;; Check if `path-true' is already inside `static-dir' + (if (string-match (regexp-quote static-dir) path-true) + (progn + ;; If so, return *only* the path considering the + ;; static directory as root. + (concat "/" (substring path-true (match-end 0)))) + (let* ((file-name-sans-static (if (string-match "/static/" path-true) + (substring path-true (match-end 0)) + (file-name-nondirectory path))) + (static-path (concat static-dir file-name-sans-static)) + (static-path-dir (file-name-directory static-path))) + ;; The `static-dir' would already exist. But if + ;; `file-name-sans-static' is "images/image.png" or + ;; "foo/bar.txt", it's likely that "`static-dir'/images" + ;; or "`static-dir'/foo" might not exist. So create + ;; those if needed below. + (unless (file-exists-p static-path-dir) + (mkdir static-path-dir :parents)) + ;; (message "[ox-hugo DBG attch rewrite] file-name: %s" file-name-sans-static) + ;; (message "[ox-hugo DBG attch rewrite] static-path: %s" static-path) + ;; (message "[ox-hugo DBG attch rewrite] static-path-dir: %s" static-path-dir) + (copy-file path-true static-path :ok-if-already-exists) + (concat "/" file-name-sans-static)))) path))) ;;;; Source Blocks @@ -1433,7 +1450,6 @@ are \"toml\" and \"yaml\"." "HUGO_BLACKFRIDAY" "HUGO_SECTION" "HUGO_BASE_DIR" - "HUGO_STATIC_IMAGES" "HUGO_CODE_FENCE" "HUGO_MENU" "HUGO_CUSTOM_FRONT_MATTER"