Configuration

The file nacara.config.json defines your site's metadata, navbar and other general configuration. This file is located at the root of your Nacara site.

Initial set up#

If you used npm init nacara to create your site, there should already be a basic configuration file.

It not here is a minimal configuration file:

{
    "url": "https://mangelmaxime.github.io",
    "baseUrl": "/Nacara/",
    "editUrl" : "https://github.com/MangelMaxime/Nacara/edit/master/docsrc",
    "title": "Nacara",
    "serverPort": 8081,
    "navbar": {
        "start": [
            {
                "section": "documentation",
                "url": "/Nacara/documentation/index.html",
                "label": "Documentation",
                "pinned": true
            }
        ],
        "end": [
            {
                "url": "https://github.com/MangelMaxime/Nacara",
                "icon": "fab fa-github",
                "label": "GitHub"
            }
        ]
    },
    "layouts": [
        "nacara-layout-standard"
    ]
}

Configuration options#

Here is a list of the main category of options you can set within your nacara.config.json file:

1. siteMetadata (object)
2. navbar (object)
3. remarkPlugins (array)
4. rehypePlugins (array)
5. layouts (array)
6. serverPort (int)
7. source (string)
8. output (string)

siteMetadata#

The siteMetadata contains common configuration data related to your site, for example: your site title, favIcon, etc.

Property	Required	Description
title	X	Title of your website
url	X	URL for your website. This is the domain part of your URL. For example, https://mangelmaxime.github.io is the URL of https://mangelmaxime.github.io/Nacara/
baseUrl	X	Base URL for your site. This is the path after the domain. For example, /Nacara/ is the baseUrl of https://mangelmaxime.github.io/Nacara/. For URLs that have no path, the baseUrl should be set to /.
favIcon		Path to your site favIcon If this field is omitted, no favIcon tag will be added to your website and the browser will use it's default behavior.
editUrl		URL for editing your documentation. Example: editUrl + 'docs/introduction.md'. If this field is omitted, there will be no "Edit" button generated.

Example

{
    "siteMetadata": {
        "title": "Nacara",
        "url": "https://mangelmaxime.github.io",
        "baseUrl": "/Nacara/",
        "editUrl" : "https://github.com/MangelMaxime/Nacara/edit/master/docsrc",
        "favIcon" : "/static/favIcon.ico"
    }
}

navbar#

All configuration related to the navbar goes here.

The navbar is split in 2 sections:

• start: the left part of the navbar which appears next to your site title and can contains textual links or dropdowns
• end: the right part of the navbar which appears at the end of it

start#

The start of the navbar consist of a list of objects of 2 types:

• LabelLink: Render a link consisting in just a label
• Dropdown: Render a dropdown, where you place a list of link

LabelLink#

Property	Required	Description
section	X	Section of the website associated to this navbar item The default layout will highlight the navbar item if the visited page is inside of the associated section
label	X	Text to display
url	X	URL to redirect to
pinned		If true, the link will be displayed on mobile display too Default: false

Example

{
    "navbar": {
    "start": [
        {
            "section": "documentation",
            "url": "/Nacara/documentation/index.html",
            "label": "Docs",
            "pinned": true
        },
        {
            "section": "showcase",
            "url": "/Nacara/showcase/index.html",
            "label": "Showcase"
        }
    ]
}

Dropdown#

Property	Required	Description
label	X	Text to display
items	X	List of items displayed in the dropdown It can be a string of value divider or an object of type DropdownLink
partial		Partial path to used for rendering the dropdown content. The partial property take precedence over the items property but you still need to fill the items. This is required for 2 reasons: Make Nacara understand your dropdown content and be able to generate the correct navigation element If the dropdown is not pinned, the items elements will be used to render the mobile menu
fullwidth		If true, the dropdown will also take the full width of the screen Default: false
pinned		If true, the link will be displayed on mobile display too Default: false

DropdownLink#

Example

{
    "navbar": {
        "start": [
            {
                "pinned": true,
                "label": "Docs",
                "items": [
                    {
                        "section": "nacara",
                        "label": "Nacara",
                        "description": "Description line1\nline2 start here",
                        "url": "/Nacara/documentation/introduction.html"
                    },
                    "divider",
                    {
                        "label": "Nacara.Layout.Standard",
                        "url": "/Nacara/documentation/layout/introduction.html"
                    }
                ]
            }
        ]
    }
}

end#

List of IconLink

Property	Required	Description
label	X	Label of the link to display The default layout use it when on mobile screen
icon	X	FontAwesome class icons part of the free pack Example: fab fa-twitter The default layout use it on tablet and desktop screen
url	X	URL to link to

Example

{
    "navbar": {
        "end": [
            {
                "url": "https://github.com/MangelMaxime/Nacara",
                "icon": "fab fa-github",
                "label": "GitHub"
            },
            {
                "url": "https://twitter.com/MangelMaxime",
                "icon": "fab fa-twitter",
                "label": "Twitter"
            }
        ]
    }
}

remarkPlugins#

This is where you configure the list of remark plugins to load.

Property	Required	Description
resolve	X	Name of the NPM package to load
property		If set, Nacara will load your plugin using pluginName.default[propertyName] Note: The only plugin I found requiring the use of this feature is gatsby-remark-vscode { "resolve": "gatsby-remark-vscode", "property": "remarkPlugin", }
options		Options to pass to the plugin

Example

{
    "remarkPlugins": [
        {
            "resolve": "gatsby-remark-vscode",
            "property": "remarkPlugin",
            "options": {
                "theme": "Atom One Light",
                "extensions": [
                    "vscode-theme-onelight"
                ]
            }
        },
        {
            "resolve": "remark-directive"
        }
    ]
}

rehypePlugins#

This is where you configure the list of rehype plugins to load.

Property	Required	Description
resolve	X	Name of the NPM package to load
property		If set, Nacara will load your plugin using pluginName.default[propertyName] Note: I don't think any rehype plugin needs this feature, but I added it to be on par with remarkPlugins feature.
options		Options to pass to the plugin

Example

{
    "rehypePlugins": [
        {
            "resolve": "rehype-slug",
        }
    ]
}

layouts#

This is where you register the different layouts supported by your website.

It consists on a list of string which can be:

• The name of an npm package

  You need to have it installed in your project
  
  

• A relative path to a .js or .jsx file.

  Learn more about custom layout here

Example

{
    "layouts": [
        "nacara-layout-standard",
        "./scripts/blog-page.jsx"
    ]
}

serverPort#

Optional

Configure on which port Nacara should start the watch server.

Default is 8080.

Example

{
    "serverPort": 8000
}

source#

Optional

Configure where the source folder is.

Default is docs

Example

{
    "source": "docsrc"
}

output#

Optional

Configure where Nacara will put the generated files.

Default is docs_deploy

Example

{
    "output": "public"
}