cloud-awesome / markdown-maker Goto Github PK

Started implementing during test refactoring, but most of the methods take this as an input.

e.g.

var table = new MdTable()
  .AddColumn("First Column")
  .AddColumn("Second Column")
  .AddColumn("Third Column");

instead of

var table = new MdTable()
  .AddColumn(new MdPlainText("First Column"))
  .AddColumn(new MdPlainText("Second Column"))
  .AddColumn(new MdPlainText("Third Column"));

Keep the original for backwards compatibility though

1. Create a document passing a POCO in the constructor

public MdDocument(string fileName, IDocumentMe pocoClass, IFileSystem fileSystem = null)

2. Create a document passing in a list of POCOs in the constructor

public MdDocument(string fileName, IEnumerable<IDocumentMe> pocoClasses, 
            IFileSystem fileSystem = null)

3. Create a new IDocumentPart type to enable it to be embedded into a wider document

e.g.

var numberedList = new MdList(MdListType.Ordered)
    .AddItem("First point")
    .AddItem("Second point")    
    .AddChildList(new MdList(MdListType.Ordered) {
        .AddItem("First child")
        .AddItem("Second child")
    })
    .AddItem("Third point")
    .AddItem("Fourth point");

produces:

- First point
- Second point
    - First child
    - Second child
- Third point
- Fourth point

rendered as:

• First point
• Second point
  • First child
  • Second child
• Third point
• Fourth point

To read and translate tables from other formats, e.g. pass in an Excel file and reference to a specific table

Add validation for each child row

To allow the return of the document's full markdown, without needing to write it out to the FileSystem

Exclude these from PR/Build pipelines, but include for local Dev and for repo consumers to run locally to actually produce real files (not mocking the filesystem...)

Also, ensure they're excluded from any Code Coverage metrics (locally and on SonarCloud)

Admittedly, it's not markdown at all, but it's a very quick, simple and useful addition (c.f. the DocfxYamlHeader class) and fits well with the other DocFX functionality so may as well keep them all together!

Related to #15

e.g.

var landingPage = new DocfxYamlFile(someFolderLandingPage)
// where someFolderLandingPage is a POCO object, based on a JSON schema

e.g. use

var quote = new MdQuote()
{
    "All the world’s a stage, and all the men and women merely players.",
    "They have their exits and their entrances;",
    "And one man in his time plays many parts."
};

on top of the existing

var quote = new MdQuote()
    .AddLine(new MdPlainText("All the world’s a stage, and all the men and women merely players."))
    .AddLine(new MdPlainText("They have their exits and their entrances;"))
    .AddLine(new MdPlainText("And one man in his time plays many parts."));

Both are required.

With the option to set bool value - true/false

Results in:

• Option

or

• Option

On top of Fitting and DocFX, as support for Azure DevOps wikis

e.g. code takes ::: instead of ```

Default to GFM but allow allow optimal parameter for AzDO flavour...

To allow for the generation of multiple .md files in one .save call

e.g.

const string folderPath = "c:/output-documents/";

var documentSet = new MdDocumentSet(folderPath)
    .AddDocument(new MdDocument(...)
    .AddDocument(new MdDocument(...)
    .AddDocument(new MdDocument(...)
    .Save(); 

Good use cases for this are:

• Validate everything before generating anything
• Potentially expensive I/O calls can be saved to a single point, as opposed to every loop round a for each, etc.

e.g.

var comment = new MdStrikeThroughText("This is a now redundant");

produces

~~This is a now redundant~~

for this:

This is a now redundant

https://docusaurus.io/

DocFX is a documentation generation engine
DoxFX's documentation is pretty poor
Don't be like DocFx

;)

Things like MdTable.AddColumn() should be able to accept MdBoldText etc. as well as plain text

(c.f. MdItalicText, but better)

These currently accept MdPlainText or string:

• MdTable.AddColumn()
• MdTableRow.AddCell()
• MdList.AddItem()
• MdQuote.AddLine()

These currently accept just a string:

• MdImage()
• MdLink()

e.g.

// This can be included in an MdParagraph instance
var footnote = new MdFootNote{
    Reference: "1", // produces [^1] in markdown
    Footnote: new MdParagraph("This is the text, that can include other children such as MdLink, etc. etc.")
};

N.B. An MdDocument instance will need a private dictionary of all footnotes, not just the usual .MarkDown getter used in other classes, that they can be processed at the end of the document.

Don't think this is supported outside of GitHub (yet?). Should it be included in a GitHub-specific namespace?

e.g. something to replace this:

var docfxMetadata = 
    "---" + Environment.NewLine +
    "uid: this_is_a_tester" + Environment.NewLine +
    "---";

new MdDocFxMetadata(key, value)

1. Yaml Header - related to #1
2. Warnings, tips, info boxes
3. Tabbed content

Also consider (but maybe later)

1. Include code from source
2. Section (Useful for adding custom CSS classes or JS events?)
   • e.g. see this MS example which is rendered like this

c.f. https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html?tabs=tabid-1%2Ctabid-a

e.g.

var comment = new MdComment("This is a comment");

produces

<!-- This is a comment -->

Before deleting and creating a new file, validate the output