feat: Support field-specific raw content with # raw (louietan#85)

* Support raw export in anki-editor--export-string

* Test anki-editor--export-string

* update reademe: Add support for raw text fields

* Add example of mixing raw and formatted fields

- Added a new example showing how to have both raw (unprocessed) and HTML-formatted fields within the same Anki note.
- Also, modified "Raw fields" example because prior version with `ANKI_FORMAT` property in `Back` subheading does not work.

Author: KaoruBB

README.org

@@ -75,7 +75,7 @@ If you use Doom Emacs, add the followings to ~packages.el~ and ~config.el~ respe
 ** Usage
 
 *** The Layout of Notes
-
+**** Note and Fields General Information
    The power of this mode comes from the builtin HTML export backend
    provided by Org, which enables you to use almost all the Org
    constructs for writing Anki notes: lists, code blocks, tables,
@@ -156,6 +156,29 @@ If you use Doom Emacs, add the followings to ~packages.el~ and ~config.el~ respe
 [fn:1] It should be noted that Org only allows letters, numbers, =_=
 and ~@~ in a tag but Anki allows more, so you may have to edit you
 Anki tags before they can be used in Org without any surprise.
+**** Controlling HTML Formatting
+By default, anki-editor converts Org syntax to HTML when exporting to Anki.
+The =:ANKI_FORMAT: nil= property can be used at the *note* level to disable this conversion for the entire note.
+
+If you want to use both raw text fields and HTML-converted fields within a single note, you can now use the =# raw= prefix *within a field* to indicate that the field's content should be treated as raw text, bypassing HTML conversion.
+Any spaces, tabs, or newlines immediately following =# raw= are ignored.
+
+#+BEGIN_SRC org
+,* Example Note with Mixed Formatting
+:PROPERTIES:
+:ANKI_NOTE_TYPE: Basic
+:END:
+
+,** Front
+This field will be converted to HTML.
+- This is a list.
+- It will be rendered as an HTML list.
+
+,** Back
+# raw
+This field will be treated as RAW text.
+It will be sent to Anki exactly as written.
+#+END_SRC
 
 *** Commands
 To see the docs for the most recent commands use M-x describe-function (for more info see [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Name-Help.html][Emacs Manual - Help Commands]])

anki-editor-tests.el

@@ -134,6 +134,24 @@ actual body of the test."
          (unwind-protect ,test
            (anki-editor-test--teardown))))))
 
+(anki-editor-deftest test--export-string-with-raw ()
+  :doc "Test `anki-editor--export-string` with `# raw` prefix."
+  :in "test-files/test.org"
+  :test
+  (progn
+    (should (equal (anki-editor--export-string "# raw content" t) "content"))
+    (should (equal (anki-editor--export-string "# raw  content" t) "content"))
+    (should (equal (anki-editor--export-string "# raw\ncontent" t) "content"))
+    (should (equal (anki-editor--export-string "# raw" t) ""))))
+
+(anki-editor-deftest test--export-string-without-raw ()
+  :doc "Test `anki-editor--export-string` without `# raw` prefix."
+  :in "test-files/test.org"
+  :test
+  (progn
+    (should (equal (anki-editor--export-string "content" t) "<p>\ncontent</p>\n"))
+    (should (equal (anki-editor--export-string "" t) ""))))
+
 (ert-deftest test--concat-fields-should-concatenate-fields-into-string ()
   "Test `anki-editor--concat-fields' should concatenate fields into string."
   (should (equal (anki-editor--concat-fields '("Front" "Back")

anki-editor.el

@@ -503,19 +503,22 @@ The implementation is borrowed and simplified from ox-html."
    (funcall oldfun link desc info)))
 
 (defun anki-editor--export-string (src fmt)
-  "Export string SRC and format it if FMT."
-  (if fmt
-      (or (org-export-string-as
-           src
-           anki-editor--ox-anki-html-backend
-           t
-           anki-editor--ox-export-ext-plist)
-          ;; 8.2.10 version of
-          ;; `org-export-filter-apply-functions'
-          ;; returns nil for an input of empty string,
-          ;; which will cause AnkiConnect to fail
-          "")
-    src))
+  "Export string SRC and format it if FMT.
+If the string starts with '# raw', return the string as is."
+  (if (and (stringp src) (string-prefix-p "# raw" src))
+      (replace-regexp-in-string "^# raw[ \t\n]*" "" src)
+    (if fmt
+        (or (org-export-string-as
+             src
+             anki-editor--ox-anki-html-backend
+             t
+             anki-editor--ox-export-ext-plist)
+            ;; 8.2.10 version of
+            ;; `org-export-filter-apply-functions'
+            ;; returns nil for an input of empty string,
+            ;; which will cause AnkiConnect to fail
+            "")
+      src)))
 
 ;;; Core primitives
 

examples.org

@@ -24,17 +24,13 @@
 * Raw fields
   :PROPERTIES:
   :ANKI_NOTE_TYPE: Basic
+  :ANKI_FORMAT: nil
   :END:
 
 ** Front
-
    How to send the content of a field or fields to Anki as is?
 
 ** Back
-   :PROPERTIES:
-   :ANKI_FORMAT: nil
-   :END:
-
    With property <code>:ANKI_FORMAT: nil</code>, content of the
    field will be sent to Anki <em>unprocessed</em>.  You can use
    whatever Anki supports, like HTML tags.
@@ -44,6 +40,17 @@
    set in any ancestor entries or at the top of the file with
    <code>#+PROPERTY: ANKI_FORMAT nil</code>, it's also possible to
    override an outer level nil format with <code>:ANKI_FORMAT: t</code>.
+* Raw and HTML-formatted fields in the same note
+  :PROPERTIES:
+  :ANKI_NOTE_TYPE: Basic
+  :END:
+
+** Front
+This field will be formatted as HTML.
+
+** Back
+# raw
+If you start a field with ~# raw~, the content will be sent to Anki as is.
 
 * Is there a shorter way to write notes?
   :PROPERTIES: