diff --git a/.gitignore b/.gitignore index 1a2d967..10c4bf8 100644 --- a/.gitignore +++ b/.gitignore @@ -62,8 +62,8 @@ instance/ # Scrapy stuff: .scrapy -# Sphinx documentation -docs/_build/ +# Documentation +docs/site/ # PyBuilder target/ diff --git a/CHANGELOG b/CHANGELOG index 249a40f..d3a64a2 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,5 @@ ## 1.0.3 (2018-05-27) - * Avoid adding the `
structure for single code blocks if the `single_block_as_tab` option is `True`. + * Avoid adding the `
` structure for single code blocks if the `single_block_as_tab` option is `True`. ## 1.0.2 (2018-05-27) * **FIX**: Fixed the Bootsrap templates diff --git a/README.md b/README.md index 97777fb..148407e 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,26 @@ -[![PyPI][pypi-image]][pypi-link] - - [pypi-image]: https://img.shields.io/pypi/v/markdown-fenced-code-tabs.svg - [pypi-link]: https://pypi.python.org/pypi/markdown-fenced-code-tabs +

+ + + + + +

# Markdown Code Tabs Extension -Generates Bootstrap HTML Tabs for Consecutive Markdown Fenced Code Blocks - -```md - ```http - GET / HTTP/1.1 - User-Agent: MyClient/1.0.0 - Accept: application/vnd.travis-ci.2+json - Host: api.travis-ci.org - - HTTP/1.1 200 OK - Content-Type: application/json - - {"hello":"world"} - ``` - - ```shell - $ travis raw / - {"hello":"world"} - ``` - - ```ruby - require 'travis' - - # You usually don't want to fire API requests manually - client = Travis::Client.new - client.get_raw('/') # => {"hello"=>"world"} - - client.get('/repos/sinatra/sinatra') - # => {"repo"=>#} - ``` -``` - -Becomes: - -![Generated result](docs/images/img1.png) +**Code Tabs** is an extension that generates a HTML structure for consecutive fenced code blocks content. -To customize the tab label, add the `fct_label` option to your code block. +## Quick start -```md - ```swift fct_label="Swift 2" - array.enumerate() - ``` +Installation is easy with pip: - ```swift fct_label="Swift 3" - array.enumerated() - ``` -``` - -![Generated result](docs/images/img2.png) - -## Installation - -Install the latest version with `pip`: -```sh +``` sh pip install markdown-fenced-code-tabs -``` - -## MkDocs Usage - -```yml -markdown_extensions: - - markdown_fenced_code_tabs: - single_block_as_tab: True -``` - -## Options - -### `single_block_as_tab` -If `True`, the extension will render a single code block as a tab. Default is `False`. - -`single_block_as_tab: True` generates: - -![True single_block_as_tab](docs/images/img3.png) +``` -`single_block_as_tab: False` generates: +For detailed installation instructions and a demo, visit +[the documentation](https://yacir.github.io/markdown-fenced-code-tabs/). -![False single_block_as_tab](docs/images/img4.png) ## Author [Yassir Barchi](http://yassir.fr) diff --git a/docs/images/img1.png b/docs/images/img1.png deleted file mode 100644 index 39e679f..0000000 Binary files a/docs/images/img1.png and /dev/null differ diff --git a/docs/images/img2.png b/docs/images/img2.png deleted file mode 100644 index a6a1d09..0000000 Binary files a/docs/images/img2.png and /dev/null differ diff --git a/docs/images/img3.png b/docs/images/img3.png deleted file mode 100644 index 9d4ac86..0000000 Binary files a/docs/images/img3.png and /dev/null differ diff --git a/docs/images/img4.png b/docs/images/img4.png deleted file mode 100644 index 17df0ac..0000000 Binary files a/docs/images/img4.png and /dev/null differ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..9026455 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,51 @@ +site_name: MD Code Tabs Extension +site_url: https://yacir.github.io/markdown-fenced-code-tabs +repo_url: https://github.com/yacir/markdown-fenced-code-tabs +edit_uri: tree/master/docs/src/ +site_description: Markdown extension who generates HTML tabs for consecutive fenced code blocks in markdown syntax +copyright: | + Copyright © 2017 - present Yassir Barchi + +docs_dir: src +theme: + name: material + language: en + palette: + primary: light-blue + accent: light-blue + logo: + icon: description + font: + text: 'Ubuntu' + code: 'Ubuntu Mono' + include_search_page: false + search_index_only: true + +pages: + - Getting Started: index.md + - Templates: templates.md + - Release Notes: release-notes.md + - Contributing & Support: contributing.md + - Licence: licence.md + +markdown_extensions: + - markdown.extensions.admonition + - markdown.extensions.codehilite: + guess_lang: false + - markdown.extensions.toc: + permalink: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.smartsymbols + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.details + - markdown_fenced_code_tabs + +extra_css: + - 'assets/css/code-tabs.css' diff --git a/docs/src/assets/css/code-tabs.css b/docs/src/assets/css/code-tabs.css new file mode 100644 index 0000000..e1652cb --- /dev/null +++ b/docs/src/assets/css/code-tabs.css @@ -0,0 +1,52 @@ +.md-fenced-code-tabs * { + box-sizing: border-box; +} + +.md-fenced-code-tabs { + box-sizing: border-box; + box-shadow: 0 2px 2px 0 rgba(0,0,0,.14), 0 1px 5px 0 rgba(0,0,0,.12), 0 3px 1px -2px rgba(0,0,0,.2); + max-width: 100%; + border-radius: .2rem; +} + +.md-fenced-code-tabs { + display: flex; + position: relative; + flex-wrap: wrap; + width: 100%; +} + +.md-fenced-code-tabs input { + position: absolute; + opacity: 0; +} + +.md-fenced-code-tabs label { + width: auto; + cursor: pointer; + font-size: 1.28rem; + padding: 1.2rem 1.6rem; +} + +.md-fenced-code-tabs input:checked + label { + color: #03a9f4; + border-bottom: 2px solid #03a9f4; +} + +.md-fenced-code-tabs .code-tabpanel { + display: none; + width: 100%; + order: 99; +} + +.md-fenced-code-tabs input:checked + label + .code-tabpanel { + display: block; +} + +.md-fenced-code-tabs pre, +.md-fenced-code-tabs .codehilite { + width: 100%; + margin: 0px; + padding-top: 5px; + padding-bottom: 5px; +} \ No newline at end of file diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 0000000..c82749f --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,23 @@ +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: It's people like you that make the open source community such a great community! 😊 + +Any type of contribution is welcome, not only code. You can help with + +- **QA**: file bug reports, the more details you can give the better (e.g. screenshots with the console open) +- **Code**: take a look at the [open issues](https://github.com/yacir/markdown-fenced-code-tabs/issues). Even if you can't write code, commenting on them, showing that you care about a given issue matters. It helps us triage them. + +## Your First Contribution + +Working on your first Pull Request? You can learn how from this *free* series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). + +## Submitting code + +Any code change should be submitted as a pull request. The description should explain what the code does and give steps to execute it. The pull request should also contain tests. + +## Code review process + +The bigger the pull request, the longer it will take to review and merge. Try to break down large pull requests in smaller chunks that are easier to review and merge. +It is also always helpful to have some context for your pull request. What was the purpose? Why does it matter to you? + +## Questions + +If you have any questions or found a bug in the source code, create an [issue](https://github.com/yacir/markdown-fenced-code-tabs/issues) (protip: do a quick search first to see if someone else didn't ask the same question before!). diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..9efe49e --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,113 @@ +# Code Tabs Extension Documentation + +!!! important "" + Migrating from an older version? Check out our [Release notes](release-notes.md). + +## Overview + +**Code Tabs** is an extension that generates a HTML structure for consecutive fenced code blocks content. It provides four features: + +- [X] The ability to choose the HTML template. +- [X] The ability to specify custom label for a tab. +- [X] The ability to enable tab generation for a single fenced code block. +- [X] The ability to specify the css class for the tab active state. + +Example: + +```` markdown +``` c +printf("HELLO WORLD!"); +``` + +``` java +System.out.println("HELLO WORLD!"); +``` + +``` python +print("HELLO WORLD!") +``` +```` + +Result: + +``` c +printf("HELLO WORLD!"); +``` + +``` java +System.out.println("HELLO WORLD!"); +``` + +``` python +print("HELLO WORLD!") +``` + +## Installation + +Installation is easy with pip: + +``` sh +pip install markdown-fenced-code-tabs +``` + +If you want to manually install it, run `python setup.py build` and `python setup.py install`. You should be able to access the extensions in Python Markdown. + +If you would like to modify the code, you can install it via: `python setup.py develop`. This method will allow you to instantly see your changes without reinstalling. + +## Usage + +In order to enable the extension just add it to your **markdown_extensions** list: + +``` yaml +markdown_extensions: + - markdown_fenced_code_tabs +``` + +This will add the extension with the default [options](#options). To configure them: + +``` yaml +markdown_extensions: + - markdown_fenced_code_tabs: + single_block_as_tab: False + active_class: 'active' + template: 'default' +``` + +!!! important + If you choose the `default` template you wiLl have to add the needed **css** as explained in the [templates documentation](templates.md). + +### Label customization + +By default the tab label is the language of the code block but it can be customized by passing the title to the `fct_label` argument placed right after the language identifier. + +Example: + +```` markdown +``` python fct_label="Python 2" +print "Bonjour" +``` + +``` python fct_label="Python 3" +print("Bonjour") +``` +```` + +Result: + +``` python fct_label="Python 2" +print "Bonjour" +``` + +``` python fct_label="Python 3" +print("Bonjour") +``` + +## Options + +The following options are provided to configure the output: + +Option | Type | Default | Description +------------------------------ | -----| --------| ----------- +`single_block_as_tab` | bool | `False` | Renders a single fenced code block as a tab. +`active_class` | string | `active` | Class name is applied to the active tab. +`template` | string | `default`| A string that specifies which HTML template should be used `default`, `bootstrap3`, or `bootstrap4`. \ No newline at end of file diff --git a/docs/src/licence.md b/docs/src/licence.md new file mode 100644 index 0000000..508a311 --- /dev/null +++ b/docs/src/licence.md @@ -0,0 +1,21 @@ +MIT License + +Copyright © 2017-present [Yassir Barchi](github@yassir.fr) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md new file mode 100644 index 0000000..2aa1f9b --- /dev/null +++ b/docs/src/release-notes.md @@ -0,0 +1,51 @@ +## Upgrading + +To upgrade Code Tabs to the latest version, use `pip`: + +``` sh +pip install --upgrade markdown-fenced-code-tabs +``` + +To inspect the currently installed version, use the following command: + +``` sh +pip show markdown-fenced-code-tabs +``` + +### Code Tabs 0.x to 1.x + +* The 0.x generates exclusively a **Bootstrap 3** based template. Starting from the 1.x, you can [choose the rendering template](templates.md). + +To keep everything working smoothly, you need to choose the `bootstrap3` template: + +``` yaml +markdown_extensions: + - markdown_fenced_code_tabs: + template: 'bootstrap3' +``` + +## Changelog + +### 1.0.3 _ May 27, 2018 + * Avoid adding the `
` structure for single code blocks if the `single_block_as_tab` option is `True`. + +### 1.0.2 _ May 27, 2018 + * **FIX**: Fixed the Bootsrap templates + +### 1.0.1 _ May 25, 2018 + * **FIX**: Fixed the missing resources + +### 1.0.0 _ May 25, 2018 + * **NEW**: Added the `active_class` option support in the configuration + * **NEW**: Added the `template` option support in the configuration + * **FIX**: Fixed the tab id issue for code blocks with same language #12 + +### 0.2.0 _ June 16, 2017 + + * Added the custom tab label option + * Fixed the missing `active` class of the first tab + * Fixed the missing `string` import + +### 0.1.0 _ March 1, 2017 + + * Initial release diff --git a/docs/src/templates.md b/docs/src/templates.md new file mode 100644 index 0000000..13f352d --- /dev/null +++ b/docs/src/templates.md @@ -0,0 +1,181 @@ +The **Code Tabs** extension allows you to choose one of the following three rendering templates. + +## Default + +The default template is dependency free and needs only CSS only to work fine. + +### Configuration + +```yaml +markdown_extensions: + - markdown_fenced_code_tabs: + template: 'default' +``` + +Here is the basic CSS that can be used. + +```css +.md-fenced-code-tabs * { + box-sizing: border-box; +} + +.md-fenced-code-tabs { + display: flex; + position: relative; + flex-wrap: wrap; + width: 100%; +} + +.md-fenced-code-tabs input { + position: absolute; + opacity: 0; +} + +.md-fenced-code-tabs label { + width: auto; + padding: 4px; + margin: 0 8px; + cursor: pointer; + color: #aaa; +} + +.md-fenced-code-tabs input:checked + label { + color: #333; +} + +.md-fenced-code-tabs .code-tabpanel { + display: none; + width: 100%; + margin-top: 10px; + order: 99; +} + +.md-fenced-code-tabs input:checked + label + .code-tabpanel { + display: block; +} + +.md-fenced-code-tabs pre, +.md-fenced-code-tabs .codehilite { + width: 100%; + margin: 0px; +} +``` + +!!! tip + Take a look to the [code-tabs css](../assets/css/code-tabs.css) of this current documentation :wink: + +### Generated HTML + +For each code block, the generated HTML code will be: + +```html + + + + +
Code 1
+``` + +Exemple: + +```` markdown +``` c +printf("HELLO WORLD!"); +``` + +``` java +System.out.println("HELLO WORLD!"); +``` +```` + +Result: + +``` HTML +
+ + +
+ ... the highlighted syntax ... +
+ + +
+ ... the highlighted syntax ... +
+
+``` + +## Bootsrapt + +If you're using a Bootstrap based theme, the only thing you'll need to is choosing the right template option depending on the Bootstrap version of you're theme. + +### Bootsrapt 3 + +```yaml +markdown_extensions: + - markdown_fenced_code_tabs: + template: 'bootstrap3' +``` + +For the same previous exemple, the generated code will be: + +``` HTML +
+ +
+
+ ... the highlighted syntax ... +
+
+ ... the highlighted syntax ... +
+
+
+``` + +### Bootsrapt 4 + +```yaml +markdown_extensions: + - markdown_fenced_code_tabs: + template: 'bootstrap4' +``` + +This time the result will be: + +``` HTML +
+ +
+
+ ... the highlighted syntax ... +
+
+ ... the highlighted syntax ... +
+
+
+``` diff --git a/setup.py b/setup.py index c623e83..c53a13d 100644 --- a/setup.py +++ b/setup.py @@ -17,7 +17,7 @@ 'Jinja2>=2.7.1' ], include_package_data=True, - description='Generates a html estructure for consecutive fenced code blocks content', + description='Generates a html structure for consecutive fenced code blocks content', author='Yassir Barchi', author_email='github@yassir.fr', license='MIT',