This plugin attempt to create inline markdown attribute using hashtags (`#`) to mimic [attribute list](https://python-markdown.github.io/extensions/attr_list/) but in better.
This plugin will convert all `"#contents` to `**contents**{: #contents .hash}` to add custom CSS. Moreover, using a custom css file, you can also style text. The plugin will convert `somes text#attribute` to `somes text**{: #attribute}**` using this file as base!
> ↪️ `#2022/01/01` will become `**2022/01/01**{: #2022/01 .hash}`
# Installation
`pip install mkdocs-custom-tags-attributes --upgrade`
First, add the plugin in your `mkdocs.yml`:
```yml
plugins:
- search
- custom-attributes
```
Note: If you have no plugin entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugin entry set, but now you have to enable it explicitly.
You need to create an `custom_attributes.css` if you want to create inline attributes!
# Configuration
You can specify the css file in your `mkdocs.yml`:
```yaml
plugins:
- search
- custom-attributes:
file: assets/css/custom_attributes.css
```
Obviously, you need to update your [extra css](https://www.mkdocs.org/user-guide/configuration/#extra_css) :
```yaml
extra_css:
- assets/css/custom_attributes.css
```
# Allowed characters
The only symbols allowed in tags are :
- `_` (underscore)
- `-` (dash)
- `/` (forward slash)
You can use these case styles/formats :
- camelCase : `#myTag`
- PascalCase : `#MyTag`
- snake_case : `#my_tag`
- kebab-case : `#my-tag`
Nested tags (like `#myTag/mySubTag`) are recognized.
# Styling usage
## Inline attributes
After this, in the css file, you can add inline attribute, automatically parsed by the plugin. Each tags must be an [css id](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors), aka prepend with `#`.
```css
#yourtags {
/* your css */
}
```
> 💭 Don't forget to escape the characters (as `\` or `/` for example!)
Little example : align to right a text.
```css
#right {
display: inline-block;
width: 100%;
text-align: right;
font-weight: normal;
}
```
The text :
```markdown
text to right#right
```
Will become :
```markdown
**text to right**{: #right}\n
```
or in html :
```html
<p><strong id="right">text to right</strong></p>
```
> 💭 You can note that I choose to use bold to mark the inline attribute. You can remove it with `font-weight: normal;` in the css file when specify your tags.
Also, some inlines attribute can be a bit strange.
First, any inline attributes placed in the end of the line will be applied on the entire paragraph.
There is a lot of possible example, so you can check the tests to saw behavior. Please, also refer to the [attribute list documentation](https://python-markdown.github.io/extensions/attr_list/).
| original | converted attribute | html |
|----------------------------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| `text to right#right` | `**text to right**{: #right}` | `<p><strong id="right">text to right</strong></p>` |
| `#FFXIV` | `**FFXIV**{: #FFXIV .hash}` | `<p><strong class="hash" id="FFXIV">FFXIV</strong></p>` |
| `#FFXIV #other` | `**FFXIV**{: #FFXIV .hash} **other**{: #other .hash}` | `<p><strong class="hash" id="FFXIV">FFXIV</strong> <strong class="hash" id="other">other</strong></p>` |
| `text1#right text2#right` | `**text1 text2**{: #right}` | `<p><strong id="right">text1 text2</strong></p>` |
| `Lorem ipsum dolor#blue sit amet, consectetur adipiscing elit#right` | `**Lorem ipsum **dolor**{: #blue} sit amet, consectetur adipiscing elit**{: #right}` | `<p><strong>Lorem ipsum </strong>dolor<strong id="right">{: #blue} sit amet, consectetur adipiscing elit</strong></p>` |
| `to right#right #FFXIV` | `to **right**{: #right} **FFXIV**{: #FFXIV .hash}` | `<p>to <strong id="right">right</strong> <strong class="hash" id="FFXIV">FFXIV</strong></p>` |
| `lorem ipsum with #FFXIV and #right`[^1] | `lorem ipsum with **FFXIV**{: #FFXIV .hash} and \n{: #right}\n` | `<p id="right">lorem ipsum with <strong class="hash" id="FFXIV">FFXIV</strong> and </p>` |
[^1]: Note the absence of word before the last tags.
**⚠️️️️ATTENTION⚠️**
> You need at last one word before each attributes to stylize unless the attributes is in the **end** of a paragraph.
> An attribute in the **end** of a paragraph will stylize all the paragraph.
💭 **Error example**:
> `lorem ipsum with #FFXIV and #blue But not right#right` -> `lorem ipsum with **FFXIV**{: #FFXIV .hash} and #blue But not right\n{: #right}\n`
## Tags
You can also custom your inline tags (hello obsidian user!) using the `.hash` class!
For example:
```css
.hash {
background-color: honeydew;
border-radius: 5px;
}
```
# Test & dev :
- The conda environment "Publish" list all requirements for developing the plugins.
- The package is developed using semantic-release, so please respect that.
- You can use flake8 and pyformat to correct your code.
To test the plugin :
```python
from custom_attributes.plugin import convert_text_attributes, convert_hashtags
import markdown as mk
config = {
'docs_dir' : 'any_folder'
'file' : 'path/to/custom_attributes.css'
}
text = 'any string with custom attributes'
print(convert_text_attributes(text, config))
```
### Functions :
- `read_custom(config: dict[str, str] -> list` : Read the css file and take each css ID and return it as a list. Return empty list if file not found.
- `cleanned_word(line: str, word_regex: str) -> str` : Check and convert the word before tags attributes if any. Return empty string if no word are found.
- `convert_hashtags (config: dict[str, str], line: str) -> str`: Convert the tags attributes from the list when reading a line.
- `convert_text_attributes(markdown: str, config: dict[str, str]) -> str` : Read an entire Markdown text to convert line per line the hashtags and tags attributes.
Raw data
{
"_id": null,
"home_page": "https://github.com/Mara-Li/mkdocs-custom-tags-attributes",
"name": "mkdocs-custom-tags-attributes",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "mkdocs,custom attributes,markdown extension,markdown,md,attribute list,attr_list",
"author": "Mara-Li",
"author_email": "mara-li@outlook.fr",
"download_url": "https://files.pythonhosted.org/packages/76/41/10c3f50367e6043200682de7b1feda4a077417437a2c3a44f9996fefd015/mkdocs-custom-tags-attributes-0.3.3.tar.gz",
"platform": null,
"description": "This plugin attempt to create inline markdown attribute using hashtags (`#`) to mimic [attribute list](https://python-markdown.github.io/extensions/attr_list/) but in better.\r\n\r\nThis plugin will convert all `\"#contents` to `**contents**{: #contents .hash}` to add custom CSS. Moreover, using a custom css file, you can also style text. The plugin will convert `somes text#attribute` to `somes text**{: #attribute}**` using this file as base!\r\n\r\n> \u21aa\ufe0f `#2022/01/01` will become `**2022/01/01**{: #2022/01 .hash}`\r\n\r\n# Installation\r\n\r\n`pip install mkdocs-custom-tags-attributes --upgrade`\r\n\r\nFirst, add the plugin in your `mkdocs.yml`:\r\n\r\n```yml\r\nplugins:\r\n - search\r\n - custom-attributes\r\n```\r\nNote: If you have no plugin entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugin entry set, but now you have to enable it explicitly.\r\n\r\nYou need to create an `custom_attributes.css` if you want to create inline attributes!\r\n\r\n# Configuration\r\n\r\nYou can specify the css file in your `mkdocs.yml`:\r\n```yaml\r\nplugins:\r\n - search\r\n - custom-attributes:\r\n file: assets/css/custom_attributes.css\r\n```\r\n\r\nObviously, you need to update your [extra css](https://www.mkdocs.org/user-guide/configuration/#extra_css) :\r\n\r\n```yaml\r\nextra_css:\r\n - assets/css/custom_attributes.css\r\n```\r\n\r\n# Allowed characters\r\n\r\nThe only symbols allowed in tags are :\r\n- `_` (underscore)\r\n- `-` (dash)\r\n- `/` (forward slash)\r\n\r\nYou can use these case styles/formats :\r\n- camelCase : `#myTag`\r\n- PascalCase : `#MyTag`\r\n- snake_case : `#my_tag`\r\n- kebab-case : `#my-tag`\r\n\r\nNested tags (like `#myTag/mySubTag`) are recognized.\r\n\r\n# Styling usage\r\n## Inline attributes\r\n\r\nAfter this, in the css file, you can add inline attribute, automatically parsed by the plugin. Each tags must be an [css id](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors), aka prepend with `#`.\r\n\r\n```css\r\n#yourtags {\r\n/* your css */\r\n}\r\n```\r\n\r\n> \ud83d\udcad Don't forget to escape the characters (as `\\` or `/` for example!)\r\n\r\nLittle example : align to right a text. \r\n\r\n```css\r\n#right {\r\n display: inline-block;\r\n width: 100%;\r\n text-align: right;\r\n font-weight: normal;\r\n}\r\n```\r\n\r\nThe text : \r\n```markdown\r\ntext to right#right\r\n```\r\nWill become :\r\n```markdown\r\n**text to right**{: #right}\\n\r\n```\r\nor in html : \r\n```html\r\n<p><strong id=\"right\">text to right</strong></p>\r\n```\r\n\r\n> \ud83d\udcad You can note that I choose to use bold to mark the inline attribute. You can remove it with `font-weight: normal;` in the css file when specify your tags.\r\n\r\nAlso, some inlines attribute can be a bit strange. \r\nFirst, any inline attributes placed in the end of the line will be applied on the entire paragraph. \r\n\r\nThere is a lot of possible example, so you can check the tests to saw behavior. Please, also refer to the [attribute list documentation](https://python-markdown.github.io/extensions/attr_list/).\r\n\r\n| original | converted attribute | html |\r\n|----------------------------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|\r\n| `text to right#right` | `**text to right**{: #right}` | `<p><strong id=\"right\">text to right</strong></p>` |\r\n| `#FFXIV` | `**FFXIV**{: #FFXIV .hash}` | `<p><strong class=\"hash\" id=\"FFXIV\">FFXIV</strong></p>` |\r\n| `#FFXIV #other` | `**FFXIV**{: #FFXIV .hash} **other**{: #other .hash}` | `<p><strong class=\"hash\" id=\"FFXIV\">FFXIV</strong> <strong class=\"hash\" id=\"other\">other</strong></p>` |\r\n| `text1#right text2#right` | `**text1 text2**{: #right}` | `<p><strong id=\"right\">text1 text2</strong></p>` |\r\n| `Lorem ipsum dolor#blue sit amet, consectetur adipiscing elit#right` | `**Lorem ipsum **dolor**{: #blue} sit amet, consectetur adipiscing elit**{: #right}` | `<p><strong>Lorem ipsum </strong>dolor<strong id=\"right\">{: #blue} sit amet, consectetur adipiscing elit</strong></p>` |\r\n| `to right#right #FFXIV` | `to **right**{: #right} **FFXIV**{: #FFXIV .hash}` | `<p>to <strong id=\"right\">right</strong> <strong class=\"hash\" id=\"FFXIV\">FFXIV</strong></p>` |\r\n| `lorem ipsum with #FFXIV and #right`[^1] | `lorem ipsum with **FFXIV**{: #FFXIV .hash} and \\n{: #right}\\n` | `<p id=\"right\">lorem ipsum with <strong class=\"hash\" id=\"FFXIV\">FFXIV</strong> and </p>` |\r\n\r\n[^1]: Note the absence of word before the last tags. \r\n\r\n**\u26a0\ufe0f\ufe0f\ufe0f\ufe0fATTENTION\u26a0\ufe0f** \r\n> You need at last one word before each attributes to stylize unless the attributes is in the **end** of a paragraph. \r\n> An attribute in the **end** of a paragraph will stylize all the paragraph. \r\n\r\n\ud83d\udcad **Error example**:\r\n> `lorem ipsum with #FFXIV and #blue But not right#right` -> `lorem ipsum with **FFXIV**{: #FFXIV .hash} and #blue But not right\\n{: #right}\\n`\r\n\r\n## Tags\r\n\r\nYou can also custom your inline tags (hello obsidian user!) using the `.hash` class!\r\nFor example:\r\n```css\r\n.hash {\r\n background-color: honeydew;\r\n border-radius: 5px;\r\n}\r\n```\r\n\r\n# Test & dev :\r\n- The conda environment \"Publish\" list all requirements for developing the plugins. \r\n- The package is developed using semantic-release, so please respect that.\r\n- You can use flake8 and pyformat to correct your code.\r\n\r\nTo test the plugin : \r\n```python\r\nfrom custom_attributes.plugin import convert_text_attributes, convert_hashtags\r\nimport markdown as mk\r\nconfig = {\r\n 'docs_dir' : 'any_folder'\r\n 'file' : 'path/to/custom_attributes.css'\r\n }\r\ntext = 'any string with custom attributes'\r\nprint(convert_text_attributes(text, config))\r\n```\r\n\r\n### Functions : \r\n- `read_custom(config: dict[str, str] -> list` : Read the css file and take each css ID and return it as a list. Return empty list if file not found.\r\n- `cleanned_word(line: str, word_regex: str) -> str` : Check and convert the word before tags attributes if any. Return empty string if no word are found.\r\n- `convert_hashtags (config: dict[str, str], line: str) -> str`: Convert the tags attributes from the list when reading a line. \r\n- `convert_text_attributes(markdown: str, config: dict[str, str]) -> str` : Read an entire Markdown text to convert line per line the hashtags and tags attributes.\r\n\r\n",
"bugtrack_url": null,
"license": "GPL-3",
"summary": "Adding custom attributes using hashtags.",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://github.com/Mara-Li/mkdocs-custom-tags-attributes"
},
"split_keywords": [
"mkdocs",
"custom attributes",
"markdown extension",
"markdown",
"md",
"attribute list",
"attr_list"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f029e01b873322fe5a2820540e0197de4f8b18e9c85d4cce92e7f6e4180aa9c2",
"md5": "3a0641cebe0c6e58d6ed38369a1aa2db",
"sha256": "b7fdc87ae45f7ba59f3294bad9f51cc98e715922bd63ae68dab407b39a0eb619"
},
"downloads": -1,
"filename": "mkdocs_custom_tags_attributes-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a0641cebe0c6e58d6ed38369a1aa2db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18744,
"upload_time": "2024-01-12T12:22:06",
"upload_time_iso_8601": "2024-01-12T12:22:06.604817Z",
"url": "https://files.pythonhosted.org/packages/f0/29/e01b873322fe5a2820540e0197de4f8b18e9c85d4cce92e7f6e4180aa9c2/mkdocs_custom_tags_attributes-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "764110c3f50367e6043200682de7b1feda4a077417437a2c3a44f9996fefd015",
"md5": "4f5793800c6c694a6536c46c2b9d44dd",
"sha256": "460812fa938272c92852fec3d824f798e44d580ef4a973321cd05a875147362f"
},
"downloads": -1,
"filename": "mkdocs-custom-tags-attributes-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "4f5793800c6c694a6536c46c2b9d44dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20819,
"upload_time": "2024-01-12T12:22:22",
"upload_time_iso_8601": "2024-01-12T12:22:22.019466Z",
"url": "https://files.pythonhosted.org/packages/76/41/10c3f50367e6043200682de7b1feda4a077417437a2c3a44f9996fefd015/mkdocs-custom-tags-attributes-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 12:22:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mara-Li",
"github_project": "mkdocs-custom-tags-attributes",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-custom-tags-attributes"
}
JSON
