# Enable AsciiDoc
> learn how to enable AsciiDoc Markup in your Hugo docs site.
To utilize AsciiDoc markup in a Hugo site, some extra configuration is required — both on your local machine and in your deployment solution (Netlify, AWS Amplify, a container image).
Once set up, you will be able to use the ascii shortcode and/or create your own.
Before you start # Read about Hugo’s security model Read about Hugo’s AsciiDoc configuration options How to enable AsciiDoc markup # The following steps have been tested with Netlify. By providing a Gemfile at the root level, Netlify knows to automatically install both Ruby and the required gems listed in the Gemfile. This may not be the case in your deployment solution. Install # Install Ruby. s brew install rbenv ruby-build Install asciidoctor. s brew install asciidoctor Create a Gemfile at the root of your Hugo project and add the following: s source 'https://rubygems.org' gem 'asciidoctor' Open your Hugo security configuration (e.g. config/_default/security.yaml). Update security.exec: We need to whitelist the ascii processor tool, asciidoctor. We need to whitelist the GEM_PATH. yaml exec: allow: - '^dart-sass-embedded$' - '^go$' - '^npx$' - '^postcss$' - '^rst2html.py$' - '^rst2html$' - '^asciidoctor$' osEnv: - (?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM|HOME|GEM_PATH)$ Configure # You can use basic AsciiDoc markup without any additional configuration. However, you can customize and extend the support by adding extensions and updating the optional attributes.
Open your Hugo markup configuration (e.g. config/_default/markup.yaml). Add the following attributes: yaml asciidocExt: attributes: {} backend: html5 extensions: [] failureLevel: fatal noHeaderOrFooter: true preserveTOC: false safeMode: unsafe sectionNumbers: false trace: false verbose: false workingFolderCurrent: true Update the list of extensions you’d like to support. Troubleshooting # It’s possible that whitelisting GEM_PATH does not work for you. In that case, try to whitelist GEM_HOME or RVM_*. See this related Github issue for historical context.


## Metadata

- **Section**: guides
- **Type**: guides
- **Author**: Lawrence Lane
- **Parent**: [Enable AsciiDoc](/guides/markups/index.txt)

## Navigation
- **Current Section**: [Enable AsciiDoc](/guides/markups/index.txt)