From 3e4c20fa0f3d4c55d4324086c0679560afefa714 Mon Sep 17 00:00:00 2001 From: Tim Carry Date: Mon, 8 Oct 2018 13:18:40 +0200 Subject: [PATCH] Adding a way to add CSS directly in markdown (#476) * docs(markdown): Allow adding CSS classes directly to Markdown * docs(markdown): Document the {my-class} syntax in the README --- docs/README.md | 19 ++++++++++++++++-- docs/package.json | 7 ++++--- docs/scripts/lib/markdown.js | 2 ++ docs/src/how-do-we-build-an-index.md | 30 ++++++++++++++++++---------- docs/src/how-does-it-work.md | 2 +- docs/src/run-your-own.md | 2 +- docs/yarn.lock | 5 +++++ 7 files changed, 49 insertions(+), 18 deletions(-) diff --git a/docs/README.md b/docs/README.md index ff547cf6..ed3689ed 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,8 +89,23 @@ All Markdown files situated in `./src` will be transformed into `.html` files in All the headers will be converted to their respective `` tag, along with a unique `#id` to allow for easy anchoring. -You can also use plain HTML inside those Markdown files if you need more -advanced styling. +You can use plain HTML inside those Markdown files if you need more advanced +styling. The custom `{my-class}` syntax is also possible if to add CSS classes +to elements. + +```markdown +This is my paragraph. {p-2} + +![Pretty image](./img.jpg) {mt-2} +``` + +```html +

This is my paragraph

+ +

+ Pretty image +

+``` ### Layouts diff --git a/docs/package.json b/docs/package.json index 89e417c5..4c51d37d 100644 --- a/docs/package.json +++ b/docs/package.json @@ -42,8 +42,12 @@ "lodash": "4.17.11", "markdown-it": "8.4.2", "markdown-it-anchor": "5.0.2", + "markdown-it-classy": "^0.2.0", "markdown-it-highlightjs": "3.0.0", "normalize.css": "8.0.0", + "p-all": "1.0.0", + "p-each-series": "1.0.0", + "p-map": "1.2.0", "pify": "3.0.0", "postcss": "6.0.23", "postcss-clean": "1.1.0", @@ -51,9 +55,6 @@ "postcss-nested": "3.0.0", "prettier": "1.14.3", "pug": "2.0.3", - "p-all": "1.0.0", - "p-each-series": "1.0.0", - "p-map": "1.2.0", "remark-cli": "5.0.0", "remark-frontmatter": "1.3.0", "remark-lint-no-trailing-spaces": "2.0.0", diff --git a/docs/scripts/lib/markdown.js b/docs/scripts/lib/markdown.js index 66a787bc..a8ea6b0a 100644 --- a/docs/scripts/lib/markdown.js +++ b/docs/scripts/lib/markdown.js @@ -4,6 +4,7 @@ import path from 'path'; import frontMatter from 'front-matter'; import markdownIt from 'markdown-it'; import markdownItAnchor from 'markdown-it-anchor'; +import markdownItClassy from 'markdown-it-classy'; import markdownItHighlight from 'markdown-it-highlightjs'; import cheerio from 'cheerio'; import pug from 'pug'; @@ -17,6 +18,7 @@ const markdown = markdownIt({ permalinkClass: 'anchor', permalinkSymbol: '', }) + .use(markdownItClassy) .use(markdownItHighlight); export default { diff --git a/docs/src/how-do-we-build-an-index.md b/docs/src/how-do-we-build-an-index.md index 2958d47c..845c0292 100644 --- a/docs/src/how-do-we-build-an-index.md +++ b/docs/src/how-do-we-build-an-index.md @@ -7,7 +7,7 @@ In this section you will learn how we build a DocSearch index from your page. ### Everything starts from your page -1st step +![1st step][2] {mt-2} _Note: We would rather avoid useless js rendering. All useful information should be available without any client-side rendering. You can use `curl` in order to @@ -15,41 +15,41 @@ have a better idea of how it would look without any client-side rendering._ ### We extract the payload thanks to your set of `selectors` -2nd step +![2nd step][3] {mt-2} We will focus on the highlighted information depending on your selectors. -### We iterate though the HTML flow and build the payload +### We iterate through the HTML flow and build the payload -3rd step +![3rd step][4] {mt-2} This payload will be the only data extracted from your page. -### We iterate though the payload and start pushing records +### We iterate through the payload and start pushing records -4th step +![4th step][5] {mt-2} We index the temporary record when we add an element to it (if `min_indexed_level` is set to `0`) ### We pile up the elements based on the current temporary record -5th step +![5th step][6] {mt-2} -Base on the position within the flow, we nest elements as much as possble to +Base on the position within the flow, we nest elements as much as possible to keep the contextual relevancy. ### We iterate until we match a `text` element -6th step +![6th step][7] {mt-2} ### We override the text element when we find a newer one -7th step +![7th step][8] {mt-2} ### We remove the stashed, deeper elements when we add a higher level -7th step +![8th step][9] {mt-2} Contextual information and hierarchy must be updated once we encounter a new level since it highlights a new sub-section not related to the previous one. @@ -58,3 +58,11 @@ If you need any further information, please [do not hesitate, send us your feedback][1]. [1]: mailto:docsearch@algolia.com +[2]: ./assets/build_index/how_do_we_build_docsearch_index_1.png +[3]: ./assets/build_index/how_do_we_build_docsearch_index_2.png +[4]: ./assets/build_index/how_do_we_build_docsearch_index_3.png +[5]: ./assets/build_index/how_do_we_build_docsearch_index_4.png +[6]: ./assets/build_index/how_do_we_build_docsearch_index_5.png +[7]: ./assets/build_index/how_do_we_build_docsearch_index_6.png +[8]: ./assets/build_index/how_do_we_build_docsearch_index_7.png +[9]: ./assets/build_index/how_do_we_build_docsearch_index_8.png diff --git a/docs/src/how-does-it-work.md b/docs/src/how-does-it-work.md index 04f7279d..67996d65 100644 --- a/docs/src/how-does-it-work.md +++ b/docs/src/how-does-it-work.md @@ -7,7 +7,7 @@ Getting up and ready with DocSearch is a straightforward process that requires three steps: you apply, we configure the crawler for you, and you integrate our Search-UI in your frontend. It is as simple as copying and pasting a snippet. -How it works +![How it works](./assets/docsearch-how-it-works.png) {mt-2} ### You apply diff --git a/docs/src/run-your-own.md b/docs/src/run-your-own.md index b753f7cf..edff75da 100644 --- a/docs/src/run-your-own.md +++ b/docs/src/run-your-own.md @@ -92,7 +92,7 @@ You can test your results by running `./docsearch playground`. This will open a web page with a search input where you can do live tests against the indexed results. -Playground +![Playground](./assets/playground.png) {mt-2} _Note that if the command fails (it can happen on non-Mac machines), you can get the same result by running a live server in the `./playground` subdirectory.\`_ diff --git a/docs/yarn.lock b/docs/yarn.lock index 504bbd5d..2fceb391 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -3659,6 +3659,11 @@ markdown-it-anchor@5.0.2: version "5.0.2" resolved "https://registry.yarnpkg.com/markdown-it-anchor/-/markdown-it-anchor-5.0.2.tgz#cdd917a05b7bf92fb736a6dae3385c6d0d0fa552" +markdown-it-classy@^0.2.0: + version "0.2.0" + resolved "https://registry.yarnpkg.com/markdown-it-classy/-/markdown-it-classy-0.2.0.tgz#832b43c9383003b8c15627198a4eef665943a50e" + integrity sha1-gytDyTgwA7jBVicZik7vZllDpQ4= + markdown-it-highlightjs@3.0.0: version "3.0.0" resolved "https://registry.yarnpkg.com/markdown-it-highlightjs/-/markdown-it-highlightjs-3.0.0.tgz#ed3dd619ca2b98e6bf2112d163bf444043340210"