verless / verless Goto Github PK

We need a verless create command to initialize a new verless project. The project name should be a command argument, so that a new project can be created like so:

$ verless create my-blog

The command should create the my-blog directory, an empty verless.yml file as well as the content, assets and templates directories.

At the moment, there's a Page field available in index pages, containing Page instances. Those instances only hold the page ID, but not the route to that page - since the route is stored as a map key internally, and the page is a value for that key.

There needs to be a way to access the route from a template. Maybe by storing the route in the page, even though this means a little redundancy.

... or fail, based on a given flag like "--force" or "--overwrite".

The test output directories shall be removed after the tests have finished.

There should be a user documentation that contains

• a configuration reference
• a template reference
• a plugin reference and
• a command reference.

Since #52, build.Plugin offers the possibility to register a page in the site model before it is written by the build.Writer. At the moment, the tags plugin writes the files itself, but once #52 is merged, it should register its pages in the site model without rendering anything itself.

I mean a route like "/". It creates the index page but also a child with name "".

Originally posted by @aligator in #75 (comment)

There should be a command like verless create file my-blog-post.md to create an initialized Markdown file.

At the moment, HasPluginKey iterates over all plugins and checks if there is a plugin with a given key. This function is called for each known plugin key manually.

It would be more flexible and alot more efficient to read the given plugin keys, see if they're in a map and load the plugin from the map with the respective key.

There should be a possibility to provide custom data as YAML, TOML or JSON files and access them in templates, or render static pages based on that data respectively. This probably will be a new plugin.

\( .__.)/

The current 'Getting started' section instructs the user to create the project files on their on, but with #24, this can be done automatically and should be used in README.md.

maybe the reading of the config file gets never closed

Originally posted by @aligator in #55 (comment)

The tree package needs to be used by all functions that perform tree- and tree path operations themselves.

Using go code generation.

Next to the actual verless version, the version command should also show the respective Git commit hash.

To avoid confusion with the route package (#84), model.Route should be renamed to model.Node.

verless create project should create a project using the files from example/.

The interface methods of build.Plugin should be re-considered.

• At the moment, the tags plugin needs the generated model.Site, because it needs to render index pages for each tag with the site's navigation. It would be more elegant to hook into the site model and let the writer write the tag index pages, just as the other index pages.

The configuration (config.Config for verless.yml) needs a new top-level string key: version. At this time, the key can be ignored in the other parts of the application.

The CLI flag descriptions should be unified. The current output looks as follows:

...
Flags:
  -h, --help            help for build
  -o, --output string   Specify an output directory.
      --overwrite       Allows overwriting an existing output directory.

The auto-generated help texts like help for build differ from our own texts: Specify an output directory.. It would be nice if the could lowercase the help texts and remove the trailing dots, e. g. specify an output directory.

At the moment, the concurrent build error handling seems to work as intended, but is far from simple. There are some aspects to consider:

• Do all errors have to be returned?
• Should the workers be shut down gracefully?
• Can the channel system be simplified?

Personally, I'd say no - yes - yes. I think only handling a single error and shutting down gracefully would drastically simplify the error handling process.

There are some fields in model.Page which should not be accessed from templates, like RelatedFQNs or Hide.

These exported fields should be made private. To be able to get and set them internally from other packages, there need to be getter and setter methods for them, and those should be accessed instead.

Instead of introducing a flag for each plugin, like --enable-atom, the plugins enabled for a project should be defined in verless.yml. The best choice would be a plugins: key with a list of plugins.

Since verless supports page tags, there also has to be a respective plugin for processing the tags.

The tags plugin should

• collect all pages that have a certain tag (store references to the pages)
• write a directory in the output path called tags, which contains a directory and the articles for each tag.

To be discussed internally

In addition to providing a custom template using Template: my-template.html, there should be a Type: my-type field that loads my-type.html from the template directory. It should be the preferred way of using different templates than page.html.

Currently, verless build builds the current directory. To build a different directory, the path has to be specified with -p: verless -p example build.

This should be changed: The build path needs to be an argument for verless build, so that the current directory can be built using verless build . and a different directory using verless build example.

This is also consistent with the planned create command.

The business logic related to filepaths and routes should be summarzied in a central route package. For example, instead of manually checking a path ...

if !strings.HasPrefix(path, "/") {
    // error
}

... the route package should be responsible for maintaining that business logic.

if !route.IsValid(path) {
    // error
}

To avoid confusion at this point, model.Route should be renamed to Node (#86).

This will supersede #58.

Content types should be configurable in the verless.yml file with an own types key:

types:
    blog-post:
        template: post.html

The only content type property at this time is template. The may infer the template file in case it isn't configured explicitly at a later time, but for this first implementation, the template key should be mandatory.

Just like in the original issue #58, the YAML key in the Markdown Front Matter should be Type.

The serve command first builds the project and then opens a webserver which serves the result.

verless serve path/to/project

A bonus if easy possible: option --watch which automatically rebuilds the project if any file in it changed.

verless sooner or later needs a plugin for generating smaller versions of images.

To be discussed internally

The verless serve command introduced in #99 has to be documented in the command reference.

Structure:

content/
    blog/
        coffee/
            making-barista-quality-espresso.md

Expected output:

target/
    blog/
        coffee/
            making-barista-quality-espresso/
                index.html

Actual output:

target/
    blog/
    coffee/
        making-barista-quality-espresso/
            index.html

using go run ./cmd/main.go build -p in -o out
it reads the folder in and outputs the folder in/out
I would expect that it is reading from in and writing to out

The funny thing about it:
The rss-plugin already does it like that, which leads to an error because out doesn't exist.

At the moment, the writer component and the tags plugin use the same template, and they have to compile it for themselves, so the same template has to be compiled multiple times.

To avoid this, there should be a global template (or tpl) package that provides a template factory function which

• compiles a template if it doesn't exist
• caches the compiled template
• returns the template from the cache.

The goimports tool should be run in the CI pipeline.

The tags plugin needs tests using the new test package.

At the moment, CircleCI's /tmp directory seems to contain a .pid file, which is released to GitHub along with the archives. This file shall be removed from the releases. Preferrably by moving the artifacts for releases in an own directory.

If the go-check CI job/one of its steps fails, the current error message isn't too helpful:

Exited with code exit status 1
CircleCI received exit code 1

There should be a clear error message for each step.

This issue is a collection of constructive feedback, especially from a technical perspective.

• What do you enjoy about verless and its development?
• What could be done better?
• What would you like to change?

My local tests fail:

GOROOT=C:\Go #gosetup
GOPATH=C:\Users\domin\go #gosetup
C:\Go\bin\go.exe test -json ./... #gosetup
=== RUN   TestBuilder_RegisterPage
--- PASS: TestBuilder_RegisterPage (0.00s)
=== RUN   TestBuilder_Dispatch
--- PASS: TestBuilder_Dispatch (0.00s)
PASS
ok  	github.com/verless/verless/builder	(cached)
=== RUN   TestMarkdown_ParsePage
--- PASS: TestMarkdown_ParsePage (0.00s)
PASS
ok  	github.com/verless/verless/parser	(cached)
=== RUN   TestSite_CreateRoute
--- PASS: TestSite_CreateRoute (0.00s)
=== RUN   TestSite_ResolveRoute
--- PASS: TestSite_ResolveRoute (0.00s)
=== RUN   TestSite_WalkRoutes
--- PASS: TestSite_WalkRoutes (0.00s)
PASS
ok  	github.com/verless/verless/model	(cached)
=== RUN   TestAtom_ProcessPage
--- PASS: TestAtom_ProcessPage (0.00s)
PASS
ok  	github.com/verless/verless/plugin/atom	(cached)
?   	github.com/verless/verless/cli	[no test files]
?   	github.com/verless/verless/cmd	[no test files]
?   	github.com/verless/verless/config	[no test files]
?   	github.com/verless/verless/core	[no test files]
?   	github.com/verless/verless/core/build	[no test files]
?   	github.com/verless/verless/fs	[no test files]
?   	github.com/verless/verless/test	[no test files]
=== RUN   TestWriter_removeOutDirIfPermitted
    writer_test.go:77: Testing 'already exists but without file'
writer_test.go:50: unexpected error: mkdir ../test-out-path: Eine Datei kann nicht erstellt werden, wenn sie bereits vorhanden ist.

    test.go:35: mkdir ../test-out-path: Eine Datei kann nicht erstellt werden, wenn sie bereits vorhanden ist.
writer_test.go:86: unexpected error: the output folder already exists and is not empty
condisder using the --overwrite flag

    test.go:35: the output folder already exists and is not empty
        condisder using the --overwrite flag
    writer_test.go:77: Testing 'already exists with overwrite'
writer_test.go:66: unexpected error: remove ../test-out-path\anyFile.txt: Der Prozess kann nicht auf die Datei zugreifen, da sie von einem anderen Prozess verwendet wird.

    test.go:35: remove ../test-out-path\anyFile.txt: Der Prozess kann nicht auf die Datei zugreifen, da sie von einem anderen Prozess verwendet wird.
    writer_test.go:77: Testing 'not exists with overwrite'
    writer_test.go:77: Testing 'normal'
writer_test.go:86: unexpected error: the output folder already exists and is not empty
condisder using the --overwrite flag

    test.go:35: the output folder already exists and is not empty
        condisder using the --overwrite flag
    writer_test.go:77: Testing 'already exists'
writer_test.go:36: unexpected error: mkdir ../test-out-path: Eine Datei kann nicht erstellt werden, wenn sie bereits vorhanden ist.

    test.go:35: mkdir ../test-out-path: Eine Datei kann nicht erstellt werden, wenn sie bereits vorhanden ist.
writer_test.go:43: unexpected error: remove ../test-out-path\anyFile.txt: Der Prozess kann nicht auf die Datei zugreifen, da sie von einem anderen Prozess verwendet wird.

    test.go:35: remove ../test-out-path\anyFile.txt: Der Prozess kann nicht auf die Datei zugreifen, da sie von einem anderen Prozess verwendet wird.
--- FAIL: TestWriter_removeOutDirIfPermitted (0.01s)
FAIL
FAIL	github.com/verless/verless/writer	0.273s

Process finished with exit code 1

This has been introduced with fb3e2a1.

The tests should cover if the actual build works. It may be useful to run this tests on a example project included in this repository.

There should be an example project in the verless repository for 3 purposes:

• Providing a quick example for potential users
• Providing a test project to build for developers
• Maybe providing a test project for unit testing

Instead of creating an entirely empty project, verless create project should create a minimalistic example page.

All Markdown files should use relative links instead of absolute ones.

Just a question: would it be possible and make sense to use relative paths? Is there any best practice?
Then the links would also work without github...

Originally posted by @aligator in #85 (comment)

The initTemplates function shall be removed from the writer.writer type. Instead, the templates should be loaded from the tpl package when rendering a page.

The site's Nav and Footer should be auto-generated by default. All top-level routes (direct child directories of content) should be added to the nav/footer.

The configuration's nav and footer keys have to be taken into account when generating the website.

The example project needs to be re-generated and re-committed after #25 has been merged.