diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,31 +1,17 @@ -# Revision history for pandocfilter - -## 0.1.0.0 -- 2026-09-13 - -- First version. Released on an unsuspecting world. - -## 0.1.1.0 -- 2025-09-15 - -- fix length and height calculations for nested lists - ## 1.0.0.0 -- 2025-09-16 -- changed source dir (`-s`) and output dir (`-o`) into optional named arguments -- added optional arguments slide lines (`-l`) and line width (`-w`) to configure slide split behavior +- first version -## 1.0.0.1 -- 2025-09-16 +## 1.1.0.0 -- 2025-09-18 - fixed issue where last slide is not affected by split filter - -## 1.0.0.2 -- 2025-09-16 - -- change slide title from h1 to h2 - -## 1.0.0.3 -- 2025-09-16 - -- fixed issue where `-o` argument is read as `-s` in the filter. +- changed slide title from h1 to h2 +- added option for external configuration through `slides.yaml`, +- added new configuration options through `slides.yaml`, `unOrphanDisplayBlocks`, `keptSentences` +- published to hackage -## 1.1.0.0 -- 2025-09-18 +## 1.1.1.0 -- 2025-09-22 -- add option for external configuration through `slides.yaml`, -- add new configuration options through `slides.yaml`, `unOrphanDisplayBlocks`, `keptSentences` +- updated documentation on source code +- updated description on README +- updated documentation on README for installation instructions diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -4,16 +4,11 @@ This pandoc filter converts markdown notes (written in plain prose) into summarized slides. The filter automatically splits long slides and resolves image target paths to new paths. +You can also configure the filter to change slide split behavior, change paragraph transformation behavior, set source and output directories for image target replacement, add optional transformations. ## Installing using cabal -You can install the package by unpacking the tarball distributable in the releases page and running `cabal install` - -```bash -tar -xvf pandoc-md-slides-.tar.gz -cd pandoc-md-slides- -cabal install -``` +You can install the package using `cabal install pandoc-md-slides`, it will install the binary `md-slides` ## Basic Usage @@ -184,7 +179,9 @@ If a path cannot be resolved based on the output file directory, then the said path is considered an external url or absolute path. Here's an example of applying arguments to the filter. -Here the markdown is converted to `json` and the resulting `json` is piped to the filter with arguments, transformed `json` is then piped to a pandoc transformation back to the format `markdown-simple_tables-multiline_tables-grid_tables`. +To pass arguments to the filter, you must apply the filter directly on the AST. +In the example below, the markdown document is converted to `json` using `pandoc` and the resulting `json` is piped to the filter with arguments. +The transformed `json` is then piped to a pandoc transformation back to the format `markdown-simple_tables-multiline_tables-grid_tables`. ```bash pandoc -t json test.md | \ @@ -282,4 +279,4 @@ $$ ``` -When enabling this option, you can make sure that colon ending sentences are kept by adding the `lastColon` predicate in `keptSentences`. +When enabling this option, you can make sure that colon ending sentences are not filtered out by the paragraph transformation by adding the `lastColon` predicate in `keptSentences`. diff --git a/app/Pandoc-filter.hs b/app/Pandoc-filter.hs --- a/app/Pandoc-filter.hs +++ b/app/Pandoc-filter.hs @@ -46,6 +46,7 @@ import Data.Yaml (decodeFileEither, ParseException) import Text.Read (readMaybe) +-- configuration settings for command line args data FilterArgs = FilterArgs { sourceDir :: Maybe String , outputDir :: Maybe String @@ -53,6 +54,7 @@ , linewidthArg :: Maybe Int } deriving (Show) +-- configuration settings for yaml file data Config = Config { maxSlideLines :: Maybe Int , maxLineWidth :: Maybe Int @@ -60,6 +62,7 @@ , unOrphanDisplayBlocks :: Maybe Bool } deriving (Show, Generic) +-- parser for named command line arguments of the filter argParser :: Parser FilterArgs argParser = FilterArgs <$> optional @@ -94,6 +97,8 @@ pattern SlideSep :: Block pattern SlideSep <- RawBlock (Format "markdown") "---" +-- Display blocks are blocks that are not plain +-- markdown paragraphs isDisplayBlock :: Block -> Bool isDisplayBlock (OrderedList _ _) = True isDisplayBlock (BulletList _) = True @@ -171,6 +176,10 @@ | (x == item && n == acc) = True | otherwise = go n xs item (acc + 1) +-- this is a lookup function that maps strings +-- with predicates +-- this is used to configure the sentences that will be +-- kept when the itemize filter is applied to paragraphs keptSentencePredLookup :: String -> ([[Inline]] -> [Inline] -> Bool) keptSentencePredLookup "important" = isImportantSentence keptSentencePredLookup "all" = (\_ _ -> True) @@ -317,6 +326,9 @@ inlineLength (Quoted _ inlines) = sum (map inlineLength inlines) inlineLength (Cite _ inlines) = sum (map inlineLength inlines) +-- calculates the component length of a block +-- this is used to estimate block that can cause overflows +-- that increase the height of a block componentLength :: Block -> Int componentLength (Plain inlines) = sum (map inlineLength inlines) componentLength (Para inlines) = sum (map inlineLength inlines) @@ -501,6 +513,7 @@ cleanBlock = intercalate "\n" (map stripStart splitLines) stripIndentMath block = block +-- replace alignment envs in latex math with the environment `aligned` replaceAlignment :: String -> Text -> Text replaceAlignment env text = ((replace (pack ("\\begin{" ++ env ++ "}")) (pack "\\begin{aligned}")) @@ -607,11 +620,15 @@ initSafe [] = Nothing initSafe l = Just (init l) +-- removes the trailing separator ('---') from the document removeTrailingSep :: Pandoc -> Pandoc removeTrailingSep (Pandoc meta blocks) | (Data.List.isSuffixOf [slideSep] blocks) = Pandoc meta (fromMaybe [] (initSafe blocks)) removeTrailingSep pandoc = pandoc +-- this filter is used when the option unOrphanDisplayBlocks is enabled +-- this filter will push sentences that end in colon (:) to the +-- next slide if the next slide is a DisplayBlock unOrphanBlocks :: [Block] -> [Block] unOrphanBlocks (header1@(Header _ _ content1) : blist@(BulletList [items]) : SlideSep : header2@(Header _ _ content2) : dblock@DisplayBlock : SlideSep : rest) | content1 == content2 = case (last items) of diff --git a/pandoc-md-slides.cabal b/pandoc-md-slides.cabal --- a/pandoc-md-slides.cabal +++ b/pandoc-md-slides.cabal @@ -1,6 +1,6 @@ cabal-version: 3.16 name: pandoc-md-slides -version: 1.1.0.0 +version: 1.1.1.0 synopsis: A pandoc filter to convert markdown notes to markdown slides description: A pandoc filter to convert markdown notes to markdown slides. Splits long slides and resolves image target paths license: MIT