Hi Robert,

In addition to the definitions.adoc that gets generated, I would like to generate individual files for each object (ex: person.adoc, address.adoc, purchase.adoc...). I'd like to reference the model from a separate document that I've written, but I would like to include the object definitions individually in specific sections rather than in a single section. Do you think this would be something useful? I haven't dived into the code yet, but I'd be willing to take a stab at it. Do you think it would be something horribly difficult as the design stands, and would it be something possibly useful to others?

Thanks!

Sebastien

Hi,
Due to factory using a concrete enum as input it is not possible to add builders for additional markup-languages without modifiying your code. I'd like to use your tool to generate output for Confluence/Jira and it would be really cool to have a simple plugin mechanism.

I've sketched a possible solution (which should not break your existing interface) in 7e0d5bc, what do you think?

Regards
André

Context :

• Many limitations on supported characters in MD and ADOC anchors, and HTML generated ids.
• Different normalization rules when cross-referencing titles over custom anchors
• We should always cross-reference a stable id instead of a moving title
• Partial AsciiDoctor support for title cross-referencing (does not work with inter-document cross-references)

Solution :

• We decide to genericize the anchor/sections/cross-references system in markup-document-builder to a LCD character set for anchors (narrower than the AsciiDoc|Markdown specification).
• No more distinct crossReferenceTitle() : only crossReference and crossReferenceRaw (no filtering, you put what you want in anchor if you know what you do)
• Each section generated with the tool will have an explicit id with anchor = normalized(title)
• All anchors are normalized this way :

- current <- trim()
- input <- current
- current <- Normalizer.normalize(Normalizer.Form.NFD)
- current <- replaceAll("\\p{Punct}+", "")
- current <- lowercase()
- current <- replaceAll("\\s+", ADOC("_") | MD("-") )
- base <- current
- current <- replaceAll("[^a-z0-9-_]+", "")
if (current.size() != base.size())
  - current <- hash(input) // use input to maximize uniqueness
end

if (ADOC)
  - current <- prefix with "_"
  - current <- suffix with "_" if endsWith("-") 
end

Notes

When a section has an explicit custom anchor, AsciiDoctor reuse it as-is for HTML id generation.

Anchors rules for documentation purpose

Markdown

Sections :

• trim
• supports UTF-8
• only lower cases
• no spaces (replaced with - )
• supported punctuation : [-] ... to be continued

Manual anchors :

• <=> HTML ids

AsciiDoc

Sections :

• no limitations

Manual anchors :

• trim
• support upper cases
• no UTF-8
• no space (replaced with _ )
• can't start with a digit
• can't end with '-' ( <> : parse error)
• supported punctuation : [:-_.] ... to be continued
• ...

HTML

HTML 4
ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters (UTF-8), digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

HTML 5 :
The value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.
There are no other restrictions on what form an ID can take; in particular, IDs can consist of just digits, start with a digit, start with an underscore, consist of just punctuation, etc.
An element's unique identifier can be used for a variety of purposes, most notably as a way to link to specific parts of a document using fragment identifiers, as a way to target an element when scripting, and as a way to style a specific element from CSS.

Hi I am trying to create a pdf document for my API's using 'swagger2markup-maven-plugin' and 'asciidoctor-maven-plugin'. I am getting following error "Failed to execute goal 'convertSwagger2markup': text must not be blank" . It fails when trying to validate boldTextLine text. Here is how my api documentation looks like

@ApiOperation(value = “Fetch User details.”,
 notes = "Return user details as a key-value pair.",
 response = User.class,
 httpMethod = "GET"
)
 @RequestMapping(value=“/users/{id}”, method = RequestMethod.GET, produces = {MediaType.APPLICATION_JSON_UTF8_VALUE})
public User<String, Object> fetchDetails(@PathVariable final String id,
 final HttpServletRequest request, final HttpServletResponse response){ 
 return new User<>();
 }

Please add support for something matching the AsciiDoc :toc: tag.

Missing table align for markdown. Any plan?

The readme contains:

<dependency>
    <groupId>io.github.robwin</groupId>
    <artifactId>markup-document-builder</artifactId>
    <version>1.0.0</version>
</dependency>

this version does not exist in maven central. Perhaps it is useful to update the readme to:

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>markup-document-builder</artifactId>
        <version>1.1.1</version>
    </dependency>

Too bad the nl.jworks.markdown_to_asciidoc dependency is not in maven central.
Swagger2Markup/swagger2markup-maven-plugin#25