Metanorma: Aequitate Verum

Creating a new document

You can create a new standard document either by:

  • Creating a new, empty AsciiDoc file

  • Using a template

  • Importing a Word Document

New file

The easiest way is to create a document from scratch, by creating an empty AsciiDoc file (.adoc) in the desired folder.

Templates

Templates get you started faster, as they provide the structure of a standard document already. If your organization provides templates, you can create a new document based on a template using the command line.

Import from Word

Importing from Word makes sense if you are moving from Word to Metanorma and need to move several, large documents. To facilitate the migration, you can use the import tool called Reverse AsciiDoc. However, the imports are not always perfect, so you need to be familiar with the Metanorma and know how to resolve error messages. If you new to Metanorma, the simplest way is to transfer your content into Metanorma AsciiDoc manually.

How to create an empty Metanorma document

Follow these steps to create a new Metanorma document:

  1. Open a text editor, for example, Atom or Visual Studio Code.

  2. Create a new AsciiDoc document by creating a new file with the extension .adoc (AsciiDoc).

    The file should look like this: filename.adoc

  3. Write the document header that contains metadata about your project. A header contains attributes and values, such as: doctype: standard. Please refer to the Adding metadata section to learn more about the document header.

  4. Write down your content using Metanorma AsciiDoc markup.

  5. Save the file to the desired location.

How to use a template

Note
Not all organizations have templates, and not all document types are supported. Head to the Metanorma GitHub repositories to check availability.
  1. Open a new terminal window on your computer.

  2. Use the cd command to navigate to the folder where the documents should be copied to.

  3. To copy the template to your machine, use the new command and specify the organization type and document.

    metanorma new PROJECT-NAME -t ORGANIZATION -d DOCUMENT-TYPE

    These examples illustrate how to use metanorma new in different setups:

    Local Metanorma installation
    metanorma new my-new-standard -t ogc -d standard
    Metanorma in Docker (MacOS)
    docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma new my-new-standard -t ogc -d standard
    Metanorma in Docker (Windows)
    docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma new my-new-standard -t ogc -d standard
  4. Edit the copied files with a text editor of your choice.

The Metanorma blog post about templates discusses the technical details of templates.

How to import a Word document

Before you can import Word files, you need to install:

Installing reverse_adoc
sudo gem install reverse_adoc
  1. Open a new terminal window on your computer.

  2. Use the cd command to navigate to the folder containing the word documents to be converted.

  3. Run the following command, specifying the original Word file and the name of the AsciiDoc file:

    w2a input.docx -o output.adoc

Please refer to the Reverse AsciiDoc Github repository for details.

Organizing your project

After creating your Metanorma document, decide how you want to organize your files. Our best practice guidance helps you decide what strategy fits for your project.