@@ -1059,3 +1059,80 @@ Lua functions for pandoc scripts.
10591059 return {pandoc.global_filter()}
10601060 -- the above is equivallent to
10611061 -- return {{Str = Str}}
1062+
1063+# Submodule mediabag
1064+
1065+The submodule `mediabag` allows accessing pandoc's media
1066+storage. The "media bag" is used when pandoc is called with the
1067+`--extract-media` or `--standalone`/`-s` option.
1068+
1069+[`insert (filepath, mime_type, contents)`]{#mediabag-insert}
1070+
1071+: Adds a new entry to pandoc's media bag.
1072+
1073+ Parameters:
1074+
1075+ `filepath`:
1076+ : filename and path relative to the output folder.
1077+
1078+ `mime_type`:
1079+ : the file's MIME type
1080+
1081+ `contents`:
1082+ : the binary contents of the file.
1083+
1084+ Usage:
1085+
1086+ local fp = "media/hello.txt"
1087+ local mt = "text/plain"
1088+ local contents = "Hello, World!"
1089+ pandoc.mediabag(fp, mt, contents)
1090+
1091+[`list ()`]{#mediabag-list}
1092+
1093+: Get a summary of the current media bag contents.
1094+
1095+ Returns: A list of elements summarizing each entry in the
1096+ media bag. The summary item contains the keys `path`,
1097+ `type`, and `length`, giving the filepath, MIME type, and
1098+ length of contents in bytes, respectively.
1099+
1100+ Usage:
1101+
1102+ -- calculate the size of the media bag.
1103+ local mb_items = pandoc.mediabag.list()
1104+ local sum = 0
1105+ for i = 1, #mb_items:
1106+ sum = sum + mb_items[i].length
1107+ end
1108+ print(sum)
1109+
1110+[`lookup (filepath)`]{#mediabag-lookup}
1111+
1112+: Lookup a media item in the media bag, returning mime type
1113+ and contents.
1114+
1115+ Parameters:
1116+
1117+ `filepath`:
1118+ : name of the file to look up.
1119+
1120+ Returns:
1121+
1122+ - the entries MIME type, or nil if the file was not found.
1123+ - contents of the file, or nil if the file was not found.
1124+
1125+ Usage:
1126+
1127+ local filename = "media/diagram.png"
1128+ local mt, contents = pandoc.mediabag.lookup(filename)
1129+
1130+[`fetch (source, base_url)`]{#mediabag-fetch}
1131+
1132+: Fetches the given source and inserts it into the media bag
1133+ using a SHA1 hash of the content as filename.
1134+
1135+ Usage:
1136+
1137+ local diagram_url = "https://pandoc.org/diagram.jpg"
1138+ pandoc.mediabag.fetch(diagram_url, ".")