diff --git a/src/JS.hs b/src/JS.hs index b6b7f23..692ddd1 100644 --- a/src/JS.hs +++ b/src/JS.hs @@ -374,8 +374,13 @@ makeTraitEditor = switchSection(traitNode, "editable"); return false; }; cancelBtn = $("", {"class":"text-button"})[0]; + markdown = $("", { + "href" : "/markdown", + "target" : "_blank", + "style" : "float:right", + "text" : "Markdown" })[0]; $(cancelBtn).append(a); - $(sectionNode).append(area, br, cancelBtn); + $(sectionNode).append(area, br, cancelBtn, markdown); |] -- | Dynamically creates a 'View.markdownEdito' (but specifically for item @@ -413,10 +418,14 @@ makeItemNotesEditor = monospace.onchange = function () { setMonospace(area, monospace.checked); }; monospaceLabel = $("", { + "href" : "/markdown", + "target" : "_blank", + "text" : "Markdown" })[0]; $(monospaceLabel).append(monospace, "monospace editor"); $(sectionNode).append( area, saveBtn, $(space), cancelBtn, $(space), - "Markdown", $(space), monospaceLabel); + markdown, $(space), monospaceLabel); |] -- | Create a new category and redirect to it (or redirect to an old category diff --git a/src/Main.hs b/src/Main.hs index b68b5c4..74cfaa6 100644 --- a/src/Main.hs +++ b/src/Main.hs @@ -677,6 +677,10 @@ main = do Spock.get "unwritten-rules" $ do lucidWithConfig $ renderUnwrittenRules + -- Markdown help + Spock.get "markdown" $ do + lucidWithConfig $ renderMarkdownHelp + -- Haskell Spock.subcomponent "haskell" $ do Spock.get root $ do diff --git a/src/View.hs b/src/View.hs index e5c66a2..6b433ac 100644 --- a/src/View.hs +++ b/src/View.hs @@ -19,6 +19,7 @@ module View renderDonate, renderCategoryPage, renderUnwrittenRules, + renderMarkdownHelp, renderSearchResults, -- * Tracking @@ -428,6 +429,12 @@ renderUnwrittenRules = wrapPage "Unwritten rules" $ do toHtml . renderMarkdownBlock =<< liftIO (T.readFile "static/unwritten-rules.md") +renderMarkdownHelp + :: (MonadIO m, MonadRandom m, MonadReader Config m) => HtmlT m () +renderMarkdownHelp = wrapPage "Markdown" $ do + toHtml . renderMarkdownBlock =<< + liftIO (T.readFile "static/markdown.md") + -- Include all the necessary things wrapPage :: (MonadIO m, MonadRandom m, MonadReader Config m) @@ -1097,7 +1104,7 @@ markdownEditor attr (view mdText -> s) submit cancel = do JS.assign val s <> cancel emptySpan "6px" - "Markdown" + a_ [href_ "/markdown", target_ "_blank"] "Markdown" emptySpan "6px" -- TODO: this jumps around when there's a lot of text, need to somehow -- prevent jumping (and in JS.makeItemNotesEditor too) @@ -1127,6 +1134,7 @@ smallMarkdownEditor attr (view mdText -> s) submit mbCancel = do textButton "cancel" $ JS.assign val s <> cancel + a_ [href_ "/markdown", target_ "_blank", style_ "float:right"] "Markdown" thisNode :: MonadRandom m => HtmlT m JQuerySelector thisNode = do diff --git a/static/help.md b/static/help.md index 83b87a3..9cc9f3e 100644 --- a/static/help.md +++ b/static/help.md @@ -6,12 +6,3 @@ The most important rule is: **it's collaborative notes, not Wikipedia**. This im > **cons:** buggy (see an example on my Github, here's the link) Second, you should write as if you were writing for a friend. If a friend asks you about X, you don't go on X's site and copy the standard “X is a powerful modern framework blah blah blah” blurb – well, don't do it here either. Here is the whole version of the [unwritten rules](/unwritten-rules), except that they are written and aren't rules. - -Markdown is supported in most places. 2 noteworthy features: you can write `[pkg](@hk)` to get a link to package `pkg` on Hackage (the full list of shortcuts is [here](https://hackage.haskell.org/package/shortcut-links/docs/ShortcutLinks-All.html), and you can mark snippets of code with `repl` to show that they come from GHCi: - -~~~~ -~~~ hs repl -> 2+2 -4 -~~~ -~~~~ diff --git a/static/markdown.md b/static/markdown.md new file mode 100644 index 0000000..e561218 --- /dev/null +++ b/static/markdown.md @@ -0,0 +1,59 @@ +# Markdown + +Markdown is supported in most places; inline Markdown in pros/cons (i.e. you can't create lists, paragraphs, etc) and ordinary Markdown elsewhere. If you haven't written Markdown before, see [this reference][Commonmark ref]. + +[Commonmark ref]: http://commonmark.org/help/ + +## Custom features + +You can write `[pkg](@hk)` to get a link to package `pkg` on Hackage (the full list of shortcuts is [here][shortcuts]). + +[shortcuts]: https://hackage.haskell.org/package/shortcut-links/docs/ShortcutLinks-All.html + +If you mark snippets of code with `repl` (to show that they come from GHCi), they will display differently: + +
+ +~~~~ +~~~ hs repl +> 2+2 +4 +~~~ +~~~~ + + + +
→
+ +		 + +~~~ hs repl +> 2+2 +4 +~~~ + +
+ +If something doesn't come from GHCi, but is still Haskell code, use `hs` or `haskell` (other languages are supported too): + +
+ +~~~~ +~~~ hs +t :: Bool +t = True +~~~ +~~~~ + + + +
→
+ +		 + +~~~ hs +t :: Bool +t = True +~~~ + +
diff --git a/static/unwritten-rules.md b/static/unwritten-rules.md index 00a7228..57a7ab7 100644 --- a/static/unwritten-rules.md +++ b/static/unwritten-rules.md @@ -2,11 +2,13 @@ If you disagree with any of these “rules”, ignore them! I don't think they are right, I just think they are better than what people would be doing otherwise if they didn't have any opinions on the matter. +For custom Markdown features we have, see [here](/markdown). + ## What to include Sort things by importance and don't try to write *everything*. The problem is that when you see 2 columns titled “pros” and “cons”, it makes people want to try and come up with as many pros/cons as possible (well, actually I don't know about *people*, but it does happen to me all the time, so it probably happens to others too). This should be avoided at all costs. Same with items themselves (e.g. libraries) – don't list all related libraries, list all libraries that could conceivably be chosen. The test is simple: if you can't say under what conditions a person would choose A over B, and B is already on the list, don't add A. I can very well relate to the vague feeling of “but A deserves to be mentioned too”, but still, don't. -On the other hand, there's another problem that should somehow be avoided. Let's take the section about books – RWH and LYAH are often recommended to people, but there's Haskell Programming From First Principles (that book at ) and it's regarded to be Totally Better Than LYAH And RWH Put Together. Even despite the fact that the former 2 are free and the latter one isn't, all 3 books still have to be mentioned – otherwise, how is the reader going to know that LYAH was omitted because it's bad and not because everyone forgot to write about it? That's the problem that comes up very often, with lists like [What I Wish I Knew When Learning Haskell](http://dev.stephendiehl.com/hask/) and [State Of The Haskell Ecosystem](https://github.com/Gabriel439/post-rfc/blob/master/sotu.md) – there are people who wouldn't trust them not because they don't trust the author's good intentions, but because they are afraid that the author simply didn't list something worth mentioning. This leads to endless Google searches and traversals of related Hackage categories (and there are way too many packages on Hackage). +On the other hand, there's another problem that should somehow be avoided. Let's take the section about books – RWH and LYAH are often recommended to people, but there's Haskell Programming From First Principles (that book at [haskellbook.com](http://haskellbook.com)) and it's regarded to be Totally Better Than LYAH And RWH Put Together. Even despite the fact that the former 2 are free and the latter one isn't, all 3 books still have to be mentioned – otherwise, how is the reader going to know that LYAH was omitted because it's bad and not because everyone forgot to write about it? That's the problem that comes up very often, with lists like [What I Wish I Knew When Learning Haskell](http://dev.stephendiehl.com/hask/) and [State Of The Haskell Ecosystem](https://github.com/Gabriel439/post-rfc/blob/master/sotu.md) – there are people who wouldn't trust them not because they don't trust the author's good intentions, but because they are afraid that the author simply didn't list something worth mentioning. This leads to endless Google searches and traversals of related Hackage categories (and there are way too many packages on Hackage). In a nutshell: