added more customization options

Author: chrisweb

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# contributing
+
+Hello developer, please have a quick look at this contributing guide before starting, you probably already know most of what's in here but it's a quick read and explains a few things that are custom to this project:
+
+if you wish to contribute to this project, please first open a [ticket in the github issues page of this project](https://github.com/chrisweb/remark-table-of-contents/issues) and explain briefly what fix or improvement you want to provide (remember the github ticket number you will need it for the commit message later on)
+
+go the [github page of this project](https://github.com/chrisweb/remark-table-of-contents) and hit the fork button  
+
+clone your fork so that you can edit the code in your local IDE (VSCode):  
+
+`git clone https://github.com/YOUR_GITHUB_USER/remark-table-of-contents.git`
+
+now you can open the project in your IDE (VSCode), happy coding...
+
+when you are done coding, please first run the linting command `npm run lint`
+
+then if there are no linting errors, create a new build using the `npm run build` command
+
+now finally you can commit your local changes to your fork (if your commit is related to a ticket start your commit message with the "#TICKER_NUMBER", this will "link" the commit to the ticket)  
+
+`git commit -m "#TICKER_NUMBER commit message"`
+
+now go to the github page of your fork and hit the pull request button to open a pull request from your fork to this projects github repository  

README.md

@@ -30,7 +30,7 @@ const nextConfig = (/*phase*/) => {
     const withMDX = WithMDX({
         extension: /\.mdx?$/,
         options: {
-            remarkPlugins: [[remarkTableOfContents, { tight: true }]],
+            remarkPlugins: [[remarkTableOfContents, { tight: true, containerAttributes: { id: 'myCustomId', class: ['myFirstCssClass', 'mySecondCssClass'] } }]],
             rehypePlugins: [],
         },
     })
@@ -53,7 +53,7 @@ const nextConfig = (/*phase*/) => {
 export default nextConfig
 ```
 
-Note: I have passed an option from **mdast-util-toc** to make the table of contents more compact, for a full list of options check out the [options section](#options) below
+Note: I have passed an option from **mdast-util-toc** to make the table of contents more compact, I also customized the container element by adding some attributes, for a full list of options check out the [options section](#options) below
 
 then create an mdx document, for example `app/articles/page.mdx` and add some content with headings and the **table of contents placeholder** (put the placeholder in the document, where you want the toc to be displayed, can be anywhere you want):
 
@@ -69,6 +69,8 @@ then create an mdx document, for example `app/articles/page.mdx` and add some co
 %toc%
 ```
 
+Note: right now the toc placeholder `%toc%` can not be inside of something else, for example if you put it inside of an html element then the plugin will not be able to find it, this could an improvement (PRs are welcome by the way 😉), other than that you can put the toc wherever you want and you can change the placeholder via the plugin options if you prefer some other string instead of the default one
+
 the output will look like this:
 
 ```md
@@ -80,25 +82,29 @@ the output will look like this:
 
 ### baz
 
-<aside>
-* [Hello World!](hello-world)
-    * [foo](#foo)
-    * [bar](#bar)
-        * [baz](#baz)
+<aside id="myCustomId" class="myFirstCssClass mySecondCssClass">
+    <nav>
+        * [Hello World!](hello-world)
+            * [foo](#foo)
+            * [bar](#bar)
+                * [baz](#baz)
+    </nav>
 </aside>
 ```
 
 ## options
 
 `options` (optional)
 
-* `options.mdx` (`boolean`, default: true) if you use mdx-js leave it to true, if you use markdown set it to false
-* `options.containerTagName` (`string`, default: 'aside') chose an element for the container that is around the toc, can by any html element you want, a `div`, a `section` ...
-* `options.hasContainer` (`boolean`, default: true) by default the toc is in a container, set to false to not use a container
-
-let's the plugin know if you are using mdx (mdx:true) or markdown (mdx: false)
+all options have default values which for most use cases should be enough, meaning there is zero configuration to do, unless you want to customize something
 
-`options.*`
+* `mdx` (`boolean`, default: true) if you use mdx-js leave it to true, if you use markdown set it to false
+* `placeholder` (`string`, default '%toc%') the placeholder that you insert into your markdown / MDX and that will get replaced by the toc
+* `hasContainer` (`boolean`, default: true) by default the toc is in a container (by default it is an `<aside>` element, see next option), set to false to not use a container
+* `containerTagName` (`string`, default: 'aside') chose an element for the container that is around the toc, can by any html element you want, a `div`, a `section` ...
+* `containerAttributes` (`object`, default {}) an object, where the keys are the attribute names and the values are the attribute values, allows you for example to add an `id` html attribute or a `class` attribute where the value is an array of class names
+* `hasNav` (`boolean`, default: true) by default the toc is inside a `<nav>` element, set to false to not use the nav element
+* `navAttributes` (`object`, default {}) an object, where the keys are the attribute names and the values are the attribute values, allows you for example to add an `id` html attribute or a `class` attribute where the value is an array of class names
 
 this plugin uses [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc) under the hood, to generate the toc, which means all **mdast-util-toc** options are supported as well:
 
@@ -112,6 +118,10 @@ this plugin uses [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc)
 
 ## TODOs
 
-* add a nav element around the toc, make it optional (or container could be one or more elements? probably more difficult to validate)
-* make the placeholder string customizable so that it can be changed to whatever string the dev wants to use
-* add an option to be able to set a class on the container (or allow any attributes?)
+* right now the toc placeholder can not be inside of something, for example if you put it into an html element then the plugin won't find the placeholder, maybe replacing my simple search with [unist-util-visit](https://www.npmjs.com/package/unist-util-visit) could allow devs to put the toc inside whatever they want!?
+
+## contributing
+
+PRs are welcome 😉
+
+To get started, please check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide of this project

dist/index.d.ts

@@ -1,9 +1,14 @@
 import type { Plugin } from 'unified';
 import { Options } from 'mdast-util-toc';
+export type IHtmlAttributes = Record<string, string | number | boolean | readonly string[]>;
 export interface IRemarkTableOfContentsOptions extends Options {
     mdx?: boolean;
     containerTagName?: string;
     hasContainer?: boolean;
+    containerAttributes?: IHtmlAttributes;
+    hasNav?: boolean;
+    navAttributes?: IHtmlAttributes;
+    placeholder?: string;
 }
 declare const remarkTableOfContents: Plugin;
 export { remarkTableOfContents };