maccoda / made-up Goto Github PK

0.0 2.0 0.0 205 KB

Static site generator for Markdown files.

License: MIT License

Rust 62.84% HTML 29.15% CSS 4.70% PowerShell 0.75% Shell 2.56%

made-up's Introduction

Made-up

Simple tool to generate a static website from a directory structure of Markdown files. Bringing back the old school simplicity and beautifying notes and documents.

Usage

Very very simple. Run the executable/binary made-up in one of the two ways:

When an argument is provided it expects this to be the root directory for all your Markdown files.
```
> made-up /root/dir/path
```
When no argument is provided it assumes it is in the root directory and will start from there.
```
> made-up
```

Pretty simple huh? Just make sure you have the correct set up as explained below and you are good to go!

Set up

Configuration

Made-Up will look for a configuration file mdup.yml in the root directory which allows the user to have a bit more control over the end product. This configuration file is not mandatory thus all fields are optional. If not specified the default will be used.

Field	Type	Description	Default
`stylesheet`	Array	List of paths for the stylesheets used for the site.	[]
`index_template`	String	Path to the user defined template to use to generate the index page. This must be a relative path from the root directory.	''
`out_dir`	String	Path to the output directory.	./out
`copy_resources`	Boolean	Specify if the stylesheet and images are to be copied or just referenced.	True
`title`	String	Title to be in the `<head>` of the generated site.	Title

Ignored Files

Not every file can make the cut for the site, so to make it easy to determine which ones do we have a simple convention. All files and directories that are to be ignored should begin with an underscore, all other markdown files will be a part of the site.

Index Template

To allow for user defined index page but not needing to maintain the current list of pages, the user is able to define the path to a Handlebars template to be used to generate the index page. If this option is not provided the default template defined by index.hbs will be applied.

The elements of the site are provided under the list element which has two properties: path and heading, representing the path to the generated HTML and the top level heading respectively.

Images

To make things simple there is a simple convention for where to store your images so Made-Up knows where to get them from when generating your site. Who would have guessed it but if you put all your images in a directory in your root directory named images Made-Up will ensure these come across to the site. They will be copied across into another images directory so you will already doing the hard job of correctly referencing for Made-Up :).

made-up's People

Contributors

Watchers

made-up's Issues

Title of page

The title of the rendered pages are all the same. That is pretty boring!
Make the title append the name of the file perhaps to make it more useful.

Inline HTML

This tag type is unhandled and is causing issues with the output produced moreso when not actually using HTML tags but referencing names. Essentially this should just be printing directly to the output as the inline HTML should be unchanged and when it isn't actually HTML then it needs to be ensured that it is printed correctly.

Page Hierarchy

Particularly for the index page but in general need to have a way to reflect the directory structure in the page hierarchy. One idea is to recursively generate index pages for each sub-directory, another is to look into a better template that has a navigation panel with a section for each directory.

Change elements provided to index template

Current the elements provided to the handlebars index template are the file names. This makes for an unattriactive index page. Instead these should be returning the main heading for that page which is guaranteed to be more human readable.

Use temporary directories

When trying to move to the Trust CI template it was made apparent the flaw in the design in that the library would perform the writing to the file, this meant that the integration test would be writing within the source code. Instead this should be changed so that during the integration testing it can create a temporary directory to write the output to.

When doing this will also mean that the ci feature can be removed as all testing should be able to be done.

Ordering of contents in generated index

The ordering of the table of contents in the generated index file is inconsistent, particularly across OS. This is causing the tests to fail as per PR #2. Need to either make the tests more robust as this is not really a failing issue or add in functionality to ensure that the files are always obtained in the same order.

Cascade the stylesheets

At the moment the configuration only allows a single styelsheet but they are called cascading style sheets so really should allow for multiple.

Nested Lists

The HTML generated incorrectly generates nested lists, it does not append the closing li tag in the correct place as shown:

<li>Point two
    <ul>
        <li>Indent point one</li>
    </ul>
</li>

Ordered lists are rendered as unordered

Currently it does not differentiate between ordered and unordered lists. All lists are rendered as unordered.

Generated index is overwritten

If the configuration has gen_index set to true it will generate the index correctly but no check is done to ensure it won't be overwritten by generated content. That is, no check is done to see if an index.md exists. It should fail if this is the case as the user has likely incorrectly configured the tool.