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)
|
Gloss is a simple blog generator for Gleam, using [Lustre](https://hexdocs.pm/lustre) and
|
||||||
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/gloss2/)
|
[lustre_ssg](https://hexdocs.pm/lustre_ssg).
|
||||||
|
|
||||||
```sh
|
Gloss runs on the JavaScript target and it's tested with Node.js.
|
||||||
gleam add gloss2
|
|
||||||
|
<!-- [![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
|
```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() {
|
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
|
- [Gloss Demo Blog](https://nicd.gitlab.io/gloss_blog)
|
||||||
|
- [User's Guide](https://nicd.gitlab.io/gloss_blog/guide.html)
|
||||||
```sh
|
- [Gloss API reference](https://nicd.gitlab.io/gloss)
|
||||||
gleam run # Run the project
|
|
||||||
gleam test # Run the tests
|
|
||||||
gleam shell # Run an Erlang shell
|
|
||||||
```
|
|
||||||
|
|
|
@ -41,7 +41,9 @@ pub type Views {
|
||||||
Views(
|
Views(
|
||||||
base: fn(Database, Configuration) -> BaseView,
|
base: fn(Database, Configuration) -> BaseView,
|
||||||
meta: fn(Database, Configuration) -> MetaView,
|
meta: fn(Database, Configuration) -> MetaView,
|
||||||
|
/// View for a single post that is rendered on its own.
|
||||||
single_post_full: fn(Database, Configuration) -> SinglePostView,
|
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,
|
single_post_list: fn(Database, Configuration) -> SinglePostView,
|
||||||
page: fn(Database, Configuration) -> PageView,
|
page: fn(Database, Configuration) -> PageView,
|
||||||
list_page: fn(Database, Configuration) -> ListPageView,
|
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/list
|
||||||
import gleam/dict.{type Dict}
|
import gleam/dict.{type Dict}
|
||||||
import gleam/result
|
import gleam/result
|
||||||
|
@ -19,10 +22,12 @@ import gloss/utils/ordered_tree
|
||||||
import gloss/config.{type Configuration}
|
import gloss/config.{type Configuration}
|
||||||
import gloss/utils/date
|
import gloss/utils/date
|
||||||
|
|
||||||
|
/// Helper struct to pass all the used views to the rendering functions.
|
||||||
pub type Views {
|
pub type Views {
|
||||||
Views(
|
Views(
|
||||||
base: BaseView,
|
base: BaseView,
|
||||||
meta: MetaView,
|
meta: MetaView,
|
||||||
|
/// View for a single post rendered on its own.
|
||||||
single_post_full: SinglePostView,
|
single_post_full: SinglePostView,
|
||||||
page: PageView,
|
page: PageView,
|
||||||
list_page: ListPageView,
|
list_page: ListPageView,
|
||||||
|
@ -30,6 +35,7 @@ pub type Views {
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Render the database and compiled content using the configuration.
|
||||||
pub fn render(
|
pub fn render(
|
||||||
db: Database,
|
db: Database,
|
||||||
compiled: CompileDatabase,
|
compiled: CompileDatabase,
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
|
//// The writer takes rendered content and writes it into the filesystem.
|
||||||
|
|
||||||
import gleam/list
|
import gleam/list
|
||||||
import gleam/dict
|
import gleam/dict
|
||||||
import gleam/result
|
import gleam/result
|
||||||
|
@ -9,6 +11,7 @@ import gloss/rendering/database.{type RenderDatabase} as _
|
||||||
import gloss/config.{type Configuration, WriteError}
|
import gloss/config.{type Configuration, WriteError}
|
||||||
import gloss/utils/priv
|
import gloss/utils/priv
|
||||||
|
|
||||||
|
/// Write the rendered content into the filesystem using lustre_ssg.
|
||||||
pub fn write(db: RenderDatabase, config: Configuration) {
|
pub fn write(db: RenderDatabase, config: Configuration) {
|
||||||
let site =
|
let site =
|
||||||
ssg.new(config.output_path)
|
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/element.{type Element, advanced, element, namespaced, text}
|
||||||
import lustre/attribute.{attribute}
|
import lustre/attribute.{attribute}
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,6 @@
|
||||||
import lustre/element.{advanced}
|
import lustre/element.{advanced}
|
||||||
|
|
||||||
|
/// Generate an XML declaration.
|
||||||
pub fn declaration() {
|
pub fn declaration() {
|
||||||
advanced("", "?xml version=\"1.0\" encoding=\"utf-8\"?", [], [], False, True)
|
advanced("", "?xml version=\"1.0\" encoding=\"utf-8\"?", [], [], False, True)
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in a new issue