Minor fix (#60)

* Add CustomProperty as a default case to the converter if the attribute isn't implemented yet.

* Add charset and http-equiv as attribute case to the converter

* Undo the RawRepresentable on enum types since the converter cannot parse it

* Make the stringValue lowercased, since the rawValue init of a type seems to be case-sensitive

* Add parent differentiation since different parents uses different types

* Rename types for code consistency

* Add a new role type

* Mark the function handler with string value of the RoleAttribute as deprecated

* Update the instructions

* Update the instructions and the readme

* Resolve issues

Instructions/Features/Conversion.md

@@ -1,11 +1,13 @@
 # Conversion
 
-The converter translates HTML into HTMLKit.
+With HTMLKit you can convert your existing HTML code into Swift. It makes the change easier, faster and it can give you an idea how the library works.
 
 ## Essential
 
 ### Call
 
+Call the converter and use the convert function. Pass the directory, where your html files are located and choose the output. We recommend to use the print option first, to get a quick preview on the output. The print shows up in the debug window of your IDE. If you choose the file option, the converter creates the swift files at the same directory you have given to the converter.
+
 ```swift
 /// [configure.swift]
 ...
@@ -45,3 +47,7 @@ struct IndexPage: Page {
     }
 }
 ```
+
+## Note
+
+Keep in mind, that maybe the converter has not covered every case. If you miss something, file an [issue](https://github.com/vapor-community/HTMLKit/issues) and let us know to make the converter better.

Instructions/Features/Localization.md

@@ -1,19 +1,67 @@
 # Localization
 
-The localization is
+HTMLKit can render your content in different languages by using Localization.
 
 ## Essential
 
 ### Registration
 
+The localization is optional, so if you want to use it, you need to register it first. Pass the directory path and the local identifier to the renderer. Keep in mind, that the directory path is the root directory where your localization files are located.
+
 ```swift
 /// [configure.swift]
+
 ...
-try Renderer().registerLocalization(atPath: path, defaultLocale: "en")
+try app.htmlkit.renderer.registerLocalization(atPath: path, defaultLocale: "en")
 ...
 ```
 
 ### Definition
 
+Define your localizations in a .json file. If you want to get to know more about definitions, take a a look at the [Lingo library](https://github.com/miroslavkovac/Lingo#usage).
+
+```swift
+/// [en.json]
+
+{
+    "Hallo.Welt": "Hello World"
+}
+```
+
+### Implementation
+
+You can retrieve the definition by calling the localized initialiser of a localizable element. Most of the phrasing elements in HTMLKit should be localizable and provide you with the specific initialiser. Please [open an issue](https://github.com/vapor-community/HTMLKit/issues), if you find an element without it.
+
 ```swift
+/// [IndexView.swift]
+
+struct IndexView: View {
+
+    var body: AnyContent {
+        Article {
+            Heading1("Hallo.Welt")
+        }
+    }
+}
+```
+
+Also the locale for the environment can be changed for example by user input. Use the environment modifier on the element and pass the specific local identifier for it.
+
+```swift
+/// [IndexView.swift]
+
+struct IndexView: View {
+
+    struct Context {
+        let date: Date
+        let locale: String
+    }
+
+    var body: AnyContent {
+        Article {
+            ...
+        }
+        .environment(locale: context.locale)
+    }
+}
 ```

Instructions/Installation.md

@@ -1,10 +1,14 @@
 # Installation
 
-## Essential
+## Requirements
+
+The requirements are
+
+## Configuration
 
 ### Packages
 
-Add the packages as dependecies to your package.
+To use HTMLKit in your project, you have to add the packages as dependecies first. Be sure to add it to your desired targets as well.
 
 ```swift
 /// [Package.swift]
@@ -27,6 +31,21 @@ targets: [
     ...
 ```
 
-## Vapor 3
+From time to time you want to update the packages. You can do it, by changing the version tags manually and saving it. You find the current version tag in the [release history](https://github.com/vapor-community/HTMLKit/releases). We recommand to read the release description first, to understand the possible changes.
+
+### Import
+
+Use the import keyword to load the module in your project files.
+
+```swift
+/// [SimpleTemplate.swift]
+
+import HTMLKit
+...
+```
+
+## Compatibiltiy
+
+### Vapor 3
 
 Check the [provider](https://github.com/vapor-community/htmlkit-vapor-provider) to learn more about supporting Vapor 3.

Instructions/Overview.md

@@ -1,22 +1,50 @@
 # Overview
 
-Render dynamic HTML templates in a *typesafe* and **performant** way!
-By using Swift's powerful language features and a pre-rendering algorithm, HTMLKit will render insanely fast templates but also catch bugs that otherwise might occur with other templating options.
+The instructions will provide you with information how to integrate HTMLKit in your project and how you can use it to write HTML by using Swift. Keep in mind, that the instructions are mainly based on a use in a vapor project.
+
+If still things are unclear, dont hesitate to [open an issue](https://github.com/vapor-community/HTMLKit/issues) or [join the discussions](https://github.com/vapor-community/HTMLKit/discussions). Also you find us on the vapor discord server.
 
 ## Index
-1. Installation
+
+1. [Installation](Instructions/Installation.md)
+
+    This section explains how to integrate the library in your project.
 
 2. Essential
-2.1 Elements
-2.2 Layouts
-2.3 Context
-2.4 Statements
+
+    2.1 [Elements](Essential/Elements.md)
+
+    This section gives an insight about the elements and how you can use it to write html.
+
+    2.2 [Layouts](Essential/Layouts.md)
+
+    This section gives an insight about the layouts and how you can use it to build a template system.
+
+    2.3 [Context](Essential/Context.md)
+
+    This section teaches you...
+
+    2.4 [Statements](Essential/Statements.md)
+
+    This section teaches you, how you can use statements for control flow.
 
 3. Features
-3.1 Localization
-3.2 Conversion
-3.3 Templating
+
+    3.1 [Localization](Features/Localization.md)
+
+    3.2 [Conversion](Features/Conversion.md)
+
+    3.3 [Templating](Features/Templating.md)
+
 
 4. Example
 
-## References
+    4.1 [Code](https://github.com/vapor-community/HTMLKit/tree/main/Instructions/Example/Page)
+
+    Shows a code example.
+
+    4.2 [Wiki](https://github.com/vapor-community/HTMLKit/wiki)
+
+    Informations about the public api.
+
+## License

README.md

@@ -1,13 +1,12 @@
 # HTMLKit
 
-Render dynamic HTML templates in a *typesafe* and **performant** way!
-By using Swift's powerful language features and a pre-rendering algorithm, HTMLKit will render insanely fast templates but also catch bugs that otherwise might occur with other templating options.
+Render dynamic HTML templates in a typesafe and performant way! By using Swift's powerful language features and a pre-rendering algorithm, HTMLKit will render insanely fast templates but also catch bugs that otherwise might occur with other templating options.
 
 ## Getting Started
 
 ### Installation
 
-Add the packages as dependecies to your package.
+Add the packages as dependecies and targets to your package file.
 
 ```swift
 /// [Package.swift]
@@ -32,9 +31,11 @@ targets: [
     ...
 ```
 
+Read the [installation instructions](https://github.com/vapor-community/HTMLKit/blob/main/Instructions/Installation.md) for more information.
+
 ### Definition
 
-Create a new file. Add the import and declare a new structure with the Protocol `Page`. Add some content to the `body` property. If you want to learn more about the definitions, take a look here.
+Create a new file in your project. Add the import at the top of your file and declare a new structure. Extend your structure by adding a [layout definition](https://github.com/vapor-community/HTMLKit/blob/main/Instructions/Essential/Layouts.md) to adopt the required properties and methods. Add your content to the `body` property.
 
 ```swift
 /// [SimplePage.swift]
@@ -66,19 +67,16 @@ struct SimplePage: Page {
 
 ### Implementation
 
-Add the import to your controller and call the structure in your handler. Use the `render(for:)` method to render the structure for the request.
+Call the structure you have created in your controller handler and use the render method to render the view for the request.
 
 ```swift
 /// [SimpleController.swift]
 
 ...
-/// 1. Add the import
-import HTMLKit
-
 final class SimpleController {
     ...
     func getPage(req: Request) throws -> EventLoopFuture<View> {
-        /// 2. Call the structure
+        /// 1. Call the structure
         return SimplePage().render(for: req)
     }
     ...
@@ -91,4 +89,10 @@ final class SimpleController {
 
 ### Conversion
 
+### Validation
+
 ## Resources
+
+### Instructions
+
+See the [instructions](https://github.com/vapor-community/HTMLKit/blob/main/Instructions/Overview.md) to learn more about the library and the features.

Sources/HTMLKit/External/Attributes/BasicAttributes.swift

@@ -3411,7 +3411,7 @@ public protocol RoleAttribute: AnyAttribute {
     /// The func adds
     ///
     ///
-    func role(_ value: String) -> Self
+    func role(_ value: Roles) -> Self
 }
 
 extension RoleAttribute {

Sources/HTMLKit/External/Components.swift

@@ -38,7 +38,7 @@ public struct MetaTitle: Component {
         }
         IF(useTwitter) {
             Meta()
-                .name(.init(rawValue: "twitter:title")!)
+                .custom(key: "name", value: "twitter:title")
                 .content(self.title.rawValue)
         }
     }
@@ -68,7 +68,7 @@ public struct MetaDescription: Component {
         }
         IF(useTwitter) {
             Meta()
-                .name(.init(rawValue: "twitter:description")!)
+                .custom(key: "name", value: "twitter:description")
                 .content(self.description.rawValue)
         }
     }
@@ -151,7 +151,7 @@ public struct Viewport: Component {
     public var body: AnyContent {
         Meta()
             .name(.viewport)
-            .content("width=\(mode.width), initial-scale=\(internalScale)")
+            .content("width=\(self.mode.width), initial-scale=\(self.internalScale)")
     }
 }
 
@@ -170,9 +170,9 @@ public struct Author: Component {
         Meta()
             .name(.author)
             .content(self.author)
-        Unwrap(handle) { handle in
+        Unwrap(self.handle) { handle in
             Meta()
-                .name(.init(rawValue: "twitter:creator")!)
+                .custom(key: "name", value: "twitter:creator")
                 .content(handle)
         }
     }

Sources/HTMLKit/External/Elements/BasicElements.swift

@@ -46,7 +46,7 @@ public struct Document: DocumentNode, BasicElement {
 
     public var content: String
 
-    public init(type: DocumentType) {
+    public init(type: Doctypes) {
         self.content = type.rawValue
     }
 }
@@ -168,9 +168,14 @@ extension Html: GlobalAttributes {
         return mutate(nonce: value)
     }
 
+    @available(*, deprecated, message: "use role(_ value: Roles) instead")
     public func role(_ value: String) -> Html {
         return mutate(role: value)
     }
+
+    public func role(_ value: Roles) -> Html {
+        return mutate(role: value.rawValue)
+    }
 
     public func hasSpellCheck(_ condition: Bool) -> Html {
         return mutate(spellcheck: condition)