From b159daa8e9dc467acfe480afedfb0cb63ff60c74 Mon Sep 17 00:00:00 2001
From: Charanjit Singh <channikhabra@users.noreply.github.com>
Date: Mon, 26 Apr 2021 15:24:25 +0530
Subject: [PATCH] docs/org.md: Add note about default export behavior of
org-mode in (#7238)
Since it seem to be a common source of confusion, this commit adds a note in
org-mode documentation referring users to consult org-mode's export
documentation when they find themselves in a pinch.
---
doc/org.md | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/doc/org.md b/doc/org.md
index 9ed20eafe..edaaa8c50 100644
--- a/doc/org.md
+++ b/doc/org.md
@@ -36,6 +36,21 @@ The following export keywords are supported:
defaults to stdout unless a target has to be given as a command
line option.
+::: {.alert .alert-info}
+Pandoc tries to be compatible with org-mode when exporting an org document. If
+you find some behavior confusing, please do refer to org-mode
+[Export-Settings](https://orgmode.org/manual/Export-Settings.html)
+documentation. For example, a common confusion
+([#3214](https://github.com/jgm/pandoc/issues/3214 "Problem with headers lower
+then 3 in org-mode reader"), [#5169](https://github.com/jgm/pandoc/issues/5169
+"org mode headings past level three converted to numbered outline list"),
+[#6145](https://github.com/jgm/pandoc/issues/6145 "Headers 4 levels deep render
+differently"), [#7236](https://github.com/jgm/pandoc/issues/7236 "In Org mode,
+Header with level > 3 are not recognized as headers")) is treatment of headers
+with level > 3 differently because org-mode sets `org-export-headline-levels`
+(configurable with `#+OPTIONS: H:3`) to 3 by default.
+:::
+
[BCP47 language tag]: https://tools.ietf.org/html/bcp47
Format-specific options