From 9420dcbc53b966efdb5a5db79d1518870df51880 Mon Sep 17 00:00:00 2001 From: Alex Gerdes Date: Fri, 17 Mar 2017 16:16:54 +0100 Subject: [PATCH 1/4] Allow pages to specify their own template. --- CCWF/Impl.hs | 15 +++++++++++++-- templates/wide.html | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 templates/wide.html diff --git a/CCWF/Impl.hs b/CCWF/Impl.hs index 769a226..75fe673 100644 --- a/CCWF/Impl.hs +++ b/CCWF/Impl.hs @@ -6,7 +6,7 @@ import Data.Char import Data.List import Data.Time import Data.Function (on) -import Data.Maybe (isJust) +import Data.Maybe (isJust, fromMaybe) import System.Directory (doesFileExist) import System.FilePath (takeBaseName) import Text.Read @@ -205,15 +205,26 @@ mkMenuCtx self = mconcat -- template (i.e. it may include substitutions), and render it as markdown -- again. Finally, apply the default template to the end result and -- relativize all URLs. +-- Pages may set a different template by setting the @template@ metadata +-- variable. applyMeAsTemplate :: Context String -> Context String -> Compiler (Item String) applyMeAsTemplate pageCtx topCtx = do + template <- getTemplate getResourceBody >>= renderPandoc >>= applyAsTemplate pageCtx >>= renderPandoc - >>= loadAndApplyTemplate "templates/default.html" topCtx + >>= loadAndApplyTemplate template topCtx >>= relativizeUrls +-- | Get the template to use for the current page. +-- If no @template@ metadata is given, @default@ is assumed. +getTemplate :: Compiler Identifier +getTemplate = do + self <- getUnderlying + mtemp <- getMetadataField self "template" + return $ fromFilePath $ "templates/" ++ (fromMaybe "default" mtemp) ++ ".html" + -- | Turn a path @p@ (stripped of prefix and extension) into @p/index.html@. mkPath :: FilePath -> FilePath mkPath "index" = "index.html" diff --git a/templates/wide.html b/templates/wide.html new file mode 100644 index 0000000..9128a0e --- /dev/null +++ b/templates/wide.html @@ -0,0 +1,42 @@ + + + + + + + + + $title$ | $coursename$ $year$ + +
+ $body$ +
+ +
+
Menu
+
+ + + From 9ad643a9f9dd2f0ebc4ea29435d1d931f50d29dc Mon Sep 17 00:00:00 2001 From: Anton Ekblad Date: Fri, 17 Mar 2017 16:27:33 +0100 Subject: [PATCH 2/4] Instructions for using custom templates and wide content. --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index da4bfb5..1f9bdcf 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,10 @@ Pages can have the following metadata items: arbitrary (but consistent; i.e. will always be the same). If `menuorder` is either `none` or a negative number, the page will not appear in the main menu at all (but can, of course, still be linked manually). +* `template`. The name of the template to use for this page. + Templates live in the `templates` subdirectory, so if a page wants to use + `mytemplate` as its template, the file `templates/mytemplate.html` will be + loaded. ### Creating a page with a submenu @@ -150,6 +154,25 @@ See the section [creating a page](#create_page); more specifically, the discussion of the `submenu` metadata item. +### Creating a page with a custom template + +See the section [creating a page](#create_page); more specifically, the +discussion of the `template` metadata item. +In short: + +1. Create a new template (or copy from `default.html` and modify) in the + `templates` directory. +2. Set the `template` metadata variable to the name of your template, on all + pages that should use the custom template. + + +### Creating a page with very wide content + +Create a page as usual, but set the `template` metadata item for the page +to `wide`. This will apply the `widecontent` CSS class to +the contents of your page. + + ### Creating a page with a quickref bar In addition to the left sidebar containing the website's main menu, pages on From 120dab8b6788ce6f6ac74e0ceb2c0f125cdf182f Mon Sep 17 00:00:00 2001 From: Anton Ekblad Date: Fri, 17 Mar 2017 16:38:59 +0100 Subject: [PATCH 3/4] Directions on modifying the look and feel of a site. --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 1f9bdcf..5ea566b 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,7 @@ Pages can have the following metadata items: See the section [creating a page](#create_page); more specifically, the discussion of the `submenu` metadata item. + ### Creating a page with a custom template @@ -192,6 +193,29 @@ Anchors are inserted just like how they are inserted for use with a submenu. The file `pages/quickref.md` contains an example usage of the quickref bar. +### Changing the look and feel of the entire website + +To change the global look of your site, you should preferably make changes to +the CSS files in the `css` subdirectory. +The file `css/style.css` governs most of the site's look, such as the fonts, +colors, text decorations, etc. + +For more drastic changes, such as completely changing the page structure or +adding some content to every single page, you will want to modify the default +template `templates/default.html`. +To only change the structure of *some* pages, you are better off creating a +new template, for use only on those pages. See the section +[creating a page with a custom template](#custom_template) for information +on how to do this. + +When modifying either templates or CSS styling, it is **very important** to +test your changes both using a normal-sized browser window, and with your +browser window shrunk to <800 pixels wide (or, even better, on an actual +mobile device). +Otherwise, you risk breaking your website for either mobile or non-mobile +devices. + + Troubleshooting --------------- From 753fbc949c68de6a9f82f74312ed7dd308fe20b1 Mon Sep 17 00:00:00 2001 From: Anton Ekblad Date: Fri, 17 Mar 2017 16:58:51 +0100 Subject: [PATCH 4/4] Add instructions on code listings. Fixes #2. --- README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ea566b..deec65b 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,43 @@ Anchors are inserted just like how they are inserted for use with a submenu. The file `pages/quickref.md` contains an example usage of the quickref bar. +### Including code listings in pages + +CCWF lets you include code listings with optional syntax highlighting on any +page. To include a one-line code snippet into running text, simply enclose it +in backticks: `` `print "hello"` ``. +These short snippets do not have syntax highlighting. + +To include longer code listings, you can enclose a block of code in triple +backticks, where each set of backticks reside on a new line: + +```` +``` +Beautiful listings +This one has no highlighting +It is a haiku +``` +```` + +To add syntax highlighting to a code block, include the name of the language +the code is written in right next to the opening triple backticks: + +```` +```haskell +fib :: Integer -> Integer +fib 1 = 1 +fib 2 = 1 +fib n = fib (n-1) + fib (n-2) +``` +```` + +If adding syntax highlighting to your code block doesn't change its appearance, +or has some other funny effect on the look of the page or the code block, your +language is most likely not supported. +In which case, simply leaving the language out will at least give you a +fixed-width font and a uniform look across code listings. + + ### Changing the look and feel of the entire website To change the global look of your site, you should preferably make changes to @@ -232,4 +269,7 @@ Troubleshooting list, it is strongly recommended to use explicit HTML in your markdown pages, since the template compiler and the markdown compiler sometimes disagree on what some particular space or newline means. - See the list of assistants on `pages/about.md` + See the list of assistants on `pages/about.md`. +* If your code listings look weird, try not specifying a language. + You won't get syntax highlighting, but you'll at least get a fixed-width font + and a uniform look without messing up your page.