Add even more docs
This commit is contained in:
parent
5f23dadde1
commit
b7a910a2f6
6 changed files with 69 additions and 15 deletions
70
README.md
70
README.md
|
@ -1,25 +1,65 @@
|
|||
# gloss2
|
||||
# gloss
|
||||
|
||||
[![Package Version](https://img.shields.io/hexpm/v/gloss2)](https://hex.pm/packages/gloss2)
|
||||
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gloss2/)
|
||||
Gloss is a simple blog generator for Gleam, using [Lustre](https://hexdocs.pm/lustre) and
|
||||
[lustre_ssg](https://hexdocs.pm/lustre_ssg).
|
||||
|
||||
```sh
|
||||
gleam add gloss2
|
||||
Gloss runs on the JavaScript target and it's tested with Node.js.
|
||||
|
||||
<!-- [![Package Version](https://img.shields.io/hexpm/v/gloss)](https://hex.pm/packages/gloss) -->
|
||||
<!-- [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gloss/) -->
|
||||
|
||||
## Quickstart
|
||||
|
||||
Gloss is not yet available on Hex. You can use it with a path dependency instead. Create a new
|
||||
Gleam project and add the following to `gleam.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
gleam_stdlib = "~> 0.36 or ~> 1.0"
|
||||
gloss = { path = "../path/to/gloss" }
|
||||
```
|
||||
|
||||
To generate a default blog, use the following in your main file:
|
||||
|
||||
```gleam
|
||||
import gloss2
|
||||
import gleam/result
|
||||
import gleam/option
|
||||
import gleam/io
|
||||
import gloss/builder
|
||||
import gloss/config.{type Configuration, Configuration}
|
||||
import gloss/defaults
|
||||
|
||||
pub fn main() {
|
||||
// TODO: An example of the project in use
|
||||
let config =
|
||||
defaults.default_config(
|
||||
"My Blog",
|
||||
"https://my.blog.example/",
|
||||
"en",
|
||||
config.Author(
|
||||
"Person McPerson",
|
||||
option.Some("person@example.com"),
|
||||
option.Some("https://fedi.instance.example/@person"),
|
||||
),
|
||||
"© Person McPerson",
|
||||
)
|
||||
|
||||
io.debug(build(config))
|
||||
}
|
||||
|
||||
pub fn build(config: Configuration) {
|
||||
// Parse the files
|
||||
use db <- result.try(builder.parse(config))
|
||||
// Compile Markdown into HTML
|
||||
let compiled = builder.compile(db, config)
|
||||
// Render content into Lustre elements
|
||||
let rendered = builder.render(db, compiled, config)
|
||||
// Write rendered content into the filesystem
|
||||
builder.write(rendered, config)
|
||||
}
|
||||
```
|
||||
|
||||
Further documentation can be found at <https://hexdocs.pm/gloss2>.
|
||||
## Documentation
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
gleam run # Run the project
|
||||
gleam test # Run the tests
|
||||
gleam shell # Run an Erlang shell
|
||||
```
|
||||
- [Gloss Demo Blog](https://nicd.gitlab.io/gloss_blog)
|
||||
- [User's Guide](https://nicd.gitlab.io/gloss_blog/guide.html)
|
||||
- [Gloss API reference](https://nicd.gitlab.io/gloss)
|
||||
|
|
|
@ -41,7 +41,9 @@ pub type Views {
|
|||
Views(
|
||||
base: fn(Database, Configuration) -> BaseView,
|
||||
meta: fn(Database, Configuration) -> MetaView,
|
||||
/// View for a single post that is rendered on its own.
|
||||
single_post_full: fn(Database, Configuration) -> SinglePostView,
|
||||
/// View for a single post rendered as part of a list.
|
||||
single_post_list: fn(Database, Configuration) -> SinglePostView,
|
||||
page: fn(Database, Configuration) -> PageView,
|
||||
list_page: fn(Database, Configuration) -> ListPageView,
|
||||
|
|
|
@ -1,3 +1,6 @@
|
|||
//// The renderer's job is to render compiled content into HTML. By default this
|
||||
//// means Lustre elements that can be later stringified.
|
||||
|
||||
import gleam/list
|
||||
import gleam/dict.{type Dict}
|
||||
import gleam/result
|
||||
|
@ -19,10 +22,12 @@ import gloss/utils/ordered_tree
|
|||
import gloss/config.{type Configuration}
|
||||
import gloss/utils/date
|
||||
|
||||
/// Helper struct to pass all the used views to the rendering functions.
|
||||
pub type Views {
|
||||
Views(
|
||||
base: BaseView,
|
||||
meta: MetaView,
|
||||
/// View for a single post rendered on its own.
|
||||
single_post_full: SinglePostView,
|
||||
page: PageView,
|
||||
list_page: ListPageView,
|
||||
|
@ -30,6 +35,7 @@ pub type Views {
|
|||
)
|
||||
}
|
||||
|
||||
/// Render the database and compiled content using the configuration.
|
||||
pub fn render(
|
||||
db: Database,
|
||||
compiled: CompileDatabase,
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//// The writer takes rendered content and writes it into the filesystem.
|
||||
|
||||
import gleam/list
|
||||
import gleam/dict
|
||||
import gleam/result
|
||||
|
@ -9,6 +11,7 @@ import gloss/rendering/database.{type RenderDatabase} as _
|
|||
import gloss/config.{type Configuration, WriteError}
|
||||
import gloss/utils/priv
|
||||
|
||||
/// Write the rendered content into the filesystem using lustre_ssg.
|
||||
pub fn write(db: RenderDatabase, config: Configuration) {
|
||||
let site =
|
||||
ssg.new(config.output_path)
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//// Bindings for Atom feed elements.
|
||||
|
||||
import lustre/element.{type Element, advanced, element, namespaced, text}
|
||||
import lustre/attribute.{attribute}
|
||||
|
||||
|
|
|
@ -1,5 +1,6 @@
|
|||
import lustre/element.{advanced}
|
||||
|
||||
/// Generate an XML declaration.
|
||||
pub fn declaration() {
|
||||
advanced("", "?xml version=\"1.0\" encoding=\"utf-8\"?", [], [], False, True)
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue