rc-lee / sitegen Goto Github PK

Continued from #16
Docusaurus' admonitions uses remark-admonitions alongside with MDX.

For SiteGen

• Take a look at remark admonitions and see if it works without MDX

or

• Create custom admonitions and styling to be used on SiteGen
• Plan styles
• Parse styles
• Create styling for generated html files

New feature to add support for a horizontal rule in Markdown. The Markdown --- should get converted to an <hr> tag.

Many code blocks generated from Markdown have a copy to clipboard feature, like the ones on Docusaurus and the ones here on GitHub.

• Check if its a bootstrap styling feature for html
• Have it implemented

In the process of installing a tool, I have run into a problem. I was going through the "How to use" section. Please, see the picture below.

It may probably be caused by "-install"

In https://github.com/rclee91/SiteGen/blob/main/bin/index.js#L107 you call a synchronous fs method, but then pass it a callback function. Only the async versions work this way.

You have a few approaches to error handling:

1. console.log() a message
2. throw and err object

I would improve this a bit. What you do in 1. is good, but would be better done on stderr vs. stdout. Also, I would consider exiting the program with an error code vs. crashing with a stack trace:

if(err) {
  console.error('Helpful error message here...');
  process.exit(-1);
}

Hey, @rclee91 I would like to add new tests to your project. Could please assign me ?

Continued from issue #16

As documented, Docusaurus has built in support for the user to write JSX inside Markdown files, that renders as React components.

A few detailed parts are required

• Being able to separate the code from regular Markdown
• Being able to parse the JSX component in Markdown. Docusaurus uses MDX as the parsing engine, so further understanding of how this engine is necessary
• Being able to run the JSX generated code inside of SiteGen to generate the correct results.
• Being able to output the correct results from the code and reflected in the same file when called inside the Markdown.

However, as MDX uses React, might have to update SiteGen to use React, or forfeit this feature altogether.

You're using a stream to process your file in https://github.com/rclee91/SiteGen/blob/main/bin/index.js#L104-L110. However, you aren't piping that into a write stream. You can pipe one stream into another, and then process things and add it to an existing output file, see https://nodejs.org/en/knowledge/advanced/streams/how-to-use-fs-create-write-stream/.

Also, your stream handling should deal with the error event, and end when the stream is finished.

In https://github.com/rclee91/SiteGen/blob/main/LICENSE#L3 you use a username vs. real name + email. In a legal document, you should consider using full name.

This feature will allow users to specify all of their SSG options in a JSON formatted configuration file instead of having to pass them all as command line arguments every time

It also will:

• The -c or --config flags accept a file path to a JSON config file.
• If the file is missing, or can't be parsed as JSON, exit with an appropriate error message.
• If the -c or --config option is provided, ignore all other options (i.e., a config file overrides other options on the command line).
• The program should ignore any options in the config file it doesn't recognize. For example, if the SSG doesn't support stylesheets, ignore a stylesheet property.
• If the config file is missing any options, assume the usual defaults.

Instead of treating paths as regular strings, prefer to use built-in modules to support it. Paths are tricky to get right, especially cross-platform. Using path.join(), etc. will help a lot.

Continued from #16

Docusaurus has meta data for Markdown files as documented.
Data includes;

• id
• title
• pagination_label
• sidebar_label
• sidebar_position
• sidebar_class_name
• hide_title
• hide_table_of_contents
• toc_min_heading_level
• toc_max_heading_level
• pagination_next
• pagination_prev
• parse_number_prefixes
• custom_edit_url
• keywords
• description
• image
• slug
• tags

To implement Front Matter for Markdown,

• Separate meta data with body content
• Choose which meta data can be stored (doesn't necessarily have to be the whole list above)

For now the meta data are 'id', 'title', 'hide_title', 'description', 'stylesheet', 'image'

• Create a Front Matter parser
• Allow the meta data to be used/referenced in the Markdown File.
  For example

---
id: SomeFileName
title: a title
image: /image.url
---
# {{ title }}
[image]( {{ image }} )

Should alternate the Markdown file content as

# a title
[image]( /image.url )

• Continued improvement (see comments below)

I have tested the HTML files in Validator. I tried to input a folder to generate multiple files + index.html. Generated pages from processed text files were valid. However, the index.html failed markup validation. Please consider reviewing the image below.

I have duplicated the file "Silver Blaze.txt", and added additional extension. "Silver Blaze.txt.t". The tool still has processed the file. I think that the tool is needed more validation.

Current static generator supports .txt files format.

I am going to add a new support for Markdown (.md) files. Specifically, I am going to implement several Markdown features: headers (1,2,3), links, italic and bold texts. In addition, I will provide documentation on Markdown support in README.md file.

With Docusaurus as a template, current markdown support for SiteGen is too basic, lacking many features.

• Swap basic markdown support for full open source one.
• Apply syntax highlights to in block code (issue #18 )
• Markdown Front Matter support (issue #19 )
• MDX and React Component support (issue #20 )
• Admonitions (issue #21 )
• #23

Continued from issue #16

Code Blocks in Docusaurus have syntax highlights, this is a very user friendly feature.

Remarkable uses highlight.js for highlighting, which may be something that can be used.

New feature to add support for inline <code> blocks. In Markdown, enclosing text in a single backtick causes the text to HTML to get rendered as <code>...text...</code>.