Refactor SEO doc

docs/seo.html

@@ -205,57 +205,22 @@
 <div id='docMainBox' class='px-16 pb-12 pt-4 overflow-auto'>
 <h1 class='mb-8'>SEO</h1>
 
-<div class='border-t'>The SEO library allows for the management and injection of dynamic data into HTML tags for the purpose of Search Engine Optimisation.
-<h2>Definition</h2>
+<div class='border-t'><p>The SEO library facilitates the optimization of Search Engine results by managing and injecting dynamic data into HTML tags.</p>
+<h2><a name="usage" class="anchor" href="#usage" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Usage</h2>
 
-<h5>Collection is used to manage all SEO and render seo setting to html data.</h5>
+<p>Initialize a <code>Collection</code> instance and register global seo configuration. The <code>Collection</code> manages SEO of all the registered models and hold global seo settings</p>
 
-<highlightjs :language='"go"' :code='"type Collection struct {\n\tregisteredSEO []*SEO\n\tglobalName    string      //default name is GlobalSEO\n\tinherited     bool        //default is true. the order is model seo setting, system seo setting, global seo setting\n\tdbContextKey  interface{} // get db from context\n\tsettingModel  interface{} // db model\n}\n"'></highlightjs>
-
-<h5>SEO is used to provide system-level default page matadata.</h5>
-
-<highlightjs :language='"go"' :code='"type SEO struct {\n\tname             string\n\tmodelTyp         reflect.Type\n\tcontextVariables map[string]contextVariablesFunc // fetch context variables from request\n\tsettingVariables interface{}                     // fetch setting variables from db\n}\n"'></highlightjs>
-
-<h5>You can use seo setting at the model level, but you need to register the model to the system SEO</h5>
-
-<highlightjs :language='"go"' :code='"type Product struct {\n\tName string\n\tSEO  Setting\n}\n"'></highlightjs>
-
-<highlightjs :language='"go"' :code='"collection.RegisterSEO(\u0026Product{})"'></highlightjs>
-
-<h5>Support customizing your own seo setting when you need more functions such as l10n, publish. Only need to implement this interface.</h5>
-
-<highlightjs :language='"go"' :code='"type QorSEOSettingInterface interface {\n\tGetName() string\n\tSetName(string)\n\tGetSEOSetting() Setting\n\tSetSEOSetting(Setting)\n\tGetVariables() Variables\n\tSetVariables(Variables)\n\tGetTitle() string\n\tGetDescription() string\n\tGetKeywords() string\n\tGetOpenGraphURL() string\n\tGetOpenGraphType() string\n\tGetOpenGraphImageURL() string\n\tGetOpenGraphImageFromMediaLibrary() media_library.MediaBox\n\tGetOpenGraphMetadata() []OpenGraphMetadata\n}\n"'></highlightjs>
-<h2><a name="usage" class="anchor" href="#usage" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>Usage</h2>
-
-<ul>
-<li><p>Create a SEO collection</p>
-
-<div class="highlight highlight-go"><pre>// Create a collection and register global seo by default
-collection := seo.NewCollection()
-
-// Change the default global name
-collection.SetGlobalName(&#34;My Global SEO&#34;)
-
-// Change the default context db key
-collection.SetDBContextKey(&#34;My DB&#34;)
-
-// Change the default seo model setting
-type MySEOSetting struct{
-	QorSEOSetting
-	publish
-	l10n
-}
-collection.SetSettingModel(&amp;MySEOSetting{})
+<div class="highlight highlight-go"><pre>collection := seo.NewCollection()
 
 // Turn off the default inherit the upper level SEO data when the current SEO data is missing
 collection.SetInherited(false)
-
-</pre></div></li>
-
-<li><p>Register and remove SEO</p>
+</pre></div>
+<h3><a name="register-models-to-seo" class="anchor" href="#register-models-to-seo" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Register models to SEO</h3>
 
 <div class="highlight highlight-go"><pre>// Register mutiple SEO by name
-collection.RegisterSEOByNames(&#34;Not Found&#34;, &#34;Internal Server Error&#34;)
+collection.RegisterSEOByNames(&#34;Product&#34;, &#34;Announcement&#34;)
 
 // Register a SEO by model
 type Product struct{
@@ -263,48 +228,73 @@ type Product struct{
 	Setting Setting
 }
 collection.RegisterSEO(&amp;Product{})
-
-// Remove a SEO
-collection.RemoveSEO(&amp;Product{}).RemoveSEO(&#34;Not Found&#34;)
-</pre></div></li>
-
-<li><p>Configure SEO</p>
-
-<div class="highlight highlight-go"><pre>// Change the default SEO name when register a SEO by model
-
-collection.RegisterSEO(&amp;Product{}).SetName(&#34;My Product&#34;)
-
-// Register a context Variable
-collection.RegisterSEO(&amp;Product{}).
-			RegisterContextVariables(&#34;og:image&#34;, func(obj interface{}, _ *Setting, _ *http.Request) string {
-						return obj.image.url
-					}).
-			RegisterContextVariables(&#34;Name&#34;, func(obj interface{}, _ *Setting, _ *http.Request) string {
-						return obj.Name
-					})
-
-
-// Register setting variable
-collection.RegisterSEO(&amp;Product{}).
-			RegisterSettingVaribles(struct{ProductTag string}{})
-</pre></div></li>
-
-<li><p>Render SEO html data</p>
+</pre></div>
+<h3><a name="remove-models-from-seo" class="anchor" href="#remove-models-from-seo" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Remove models from SEO</h3>
+
+<pre><code>// Remove by struct
+collection.RemoveSEO(&amp;Product{})
+// Remove by name
+collection.RemoveSEO(&#34;Not Found&#34;)
+</code></pre>
+<h2><a name="configuration" class="anchor" href="#configuration" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Configuration</h2>
+<h3><a name="change-the-default-seo-name" class="anchor" href="#change-the-default-seo-name" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Change the default SEO name</h3>
+
+<div class="highlight highlight-go"><pre>collection.RegisterSEO(&amp;Product{}).SetName(&#34;My Product&#34;)
+</pre></div>
+<h3><a name="register-customized-variables" class="anchor" href="#register-customized-variables" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Register customized variables</h3>
+
+<div class="highlight highlight-go"><pre>collection.RegisterSEO(&amp;Product{}).
+	RegisterContextVariables(&#34;og:image&#34;, func(obj interface{}, _ *Setting, _ *http.Request) string {
+		// this will render &#34;og:image&#34; with the value of the object in the current request
+		return obj.image.url
+	}).
+	RegisterContextVariables(&#34;Name&#34;, func(obj interface{}, _ *Setting, _ *http.Request) string {
+		return obj.Name
+	})
+</pre></div>
+<h3><a name="register-setting-variable" class="anchor" href="#register-setting-variable" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Register setting variable</h3>
+
+<div class="highlight highlight-go"><pre>collection.RegisterSEO(&amp;Product{}).RegisterSettingVaribles(struct{ProductTag string}{})
+</pre></div>
+<h3><a name="render-seo-html-data" class="anchor" href="#render-seo-html-data" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Render SEO html data</h3>
 
 <div class="highlight highlight-go"><pre>// Render Global SEO
 collection.RenderGlobal(request)
 
-// Render SEO by a name
+// Render SEO by name
 collection.Render(&#34;product&#34;, request)
 
-// Render SEO by a model
+// Render SEO by model
 collection.Render(Product{}, request)
-</pre></div></li>
-</ul>
+</pre></div>
+<h2><a name="customization" class="anchor" href="#customization" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Customization</h2>
+<p>You can customize your SEO settings by implementing the interface and adding functions such as l10n and publish.</p>
+
+<highlightjs :language='"go"' :code='"type QorSEOSettingInterface interface {\n\tGetName() string\n\tSetName(string)\n\tGetSEOSetting() Setting\n\tSetSEOSetting(Setting)\n\tGetVariables() Variables\n\tSetVariables(Variables)\n\tGetTitle() string\n\tGetDescription() string\n\tGetKeywords() string\n\tGetOpenGraphURL() string\n\tGetOpenGraphType() string\n\tGetOpenGraphImageURL() string\n\tGetOpenGraphImageFromMediaLibrary() media_library.MediaBox\n\tGetOpenGraphMetadata() []OpenGraphMetadata\n}\n"'></highlightjs>
 
 <h2>Example</h2>
 
 <highlightjs :language='"go"' :code='"var SeoCollection *seo.Collection\n\nfunc ConfigureSeo(b *presets.Builder, db *gorm.DB) {\n\tSeoCollection = seo.NewCollection()\n\tSeoCollection.RegisterSEO(\u0026models.Post{}).RegisterContextVariables(\n\t\t\"Title\",\n\t\tfunc(object interface{}, _ *seo.Setting, _ *http.Request) string {\n\t\t\tif article, ok := object.(models.Post); ok {\n\t\t\t\treturn article.Title\n\t\t\t}\n\t\t\treturn \"\"\n\t\t},\n\t).RegisterSettingVaribles(struct{ Test string }{})\n\tSeoCollection.RegisterSEOByNames(\"Not Found\", \"Internal Server Error\")\n\tSeoCollection.Configure(b, db)\n}\n"'></highlightjs>
+<h2><a name="definition" class="anchor" href="#definition" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>Definition</h2>
+
+<p><code>Collection</code> manages SEO of all the registered models and hold global seo settings.</p>
+
+<highlightjs :language='"go"' :code='"type Collection struct {\n\tregisteredSEO []*SEO\n\tglobalName    string      //default name is GlobalSEO\n\tinherited     bool        //default is true. the order is model seo setting, system seo setting, global seo setting\n\tdbContextKey  interface{} // get db from context\n\tsettingModel  interface{} // db model\n}\n"'></highlightjs>
+<p><code>SEO</code> provides system-level default page matadata.</p>
+
+<highlightjs :language='"go"' :code='"type SEO struct {\n\tname             string\n\tmodelTyp         reflect.Type\n\tcontextVariables map[string]contextVariablesFunc // fetch context variables from request\n\tsettingVariables interface{}                     // fetch setting variables from db\n}\n"'></highlightjs>
+<p>You can use seo setting at the model level, but you need to register the model to the system SEO</p>
+
+<highlightjs :language='"go"' :code='"type Product struct {\n\tName string\n\tSEO  Setting\n}\n"'></highlightjs>
+
+<highlightjs :language='"go"' :code='"collection.RegisterSEO(\u0026Product{})"'></highlightjs>
 </div>
 </div>
 </div>

docsrc/content/basics/seo.go

@@ -8,48 +8,22 @@ import (
 )
 
 var SEO = Doc(
-	htmlgo.Text("The SEO library allows for the management and injection of dynamic data into HTML tags for the purpose of Search Engine Optimisation."),
-	htmlgo.H2("Definition"),
-	htmlgo.H5(`Collection is used to manage all SEO and render seo setting to html data.`),
-	ch.Code(generated.SeoCollectionDefinition).Language("go"),
-	htmlgo.H5(`SEO is used to provide system-level default page matadata.`),
-	ch.Code(generated.SeoDefinition).Language("go"),
-	htmlgo.H5(`You can use seo setting at the model level, but you need to register the model to the system SEO`),
-	ch.Code(generated.SeoModelExample).Language("go"),
-	ch.Code(`collection.RegisterSEO(&Product{})`).Language("go"),
-	htmlgo.H5(`Support customizing your own seo setting when you need more functions such as l10n, publish. Only need to implement this interface.`),
-	ch.Code(generated.QorSEOSettingInterface).Language("go"),
 	Markdown(`
+The SEO library facilitates the optimization of Search Engine results by managing and injecting dynamic data into HTML tags.
+
 ## Usage
-- Create a SEO collection
+Initialize a ~~Collection~~ instance. The ~~Collection~~ manages all the registered models and hold global seo settings
 ~~~go
-// Create a collection and register global seo by default
 collection := seo.NewCollection()
 
-// Change the default global name
-collection.SetGlobalName("My Global SEO")
-
-// Change the default context db key
-collection.SetDBContextKey("My DB")
-
-// Change the default seo model setting
-type MySEOSetting struct{
-	QorSEOSetting
-	publish
-	l10n
-}
-collection.SetSettingModel(&MySEOSetting{})
-
 // Turn off the default inherit the upper level SEO data when the current SEO data is missing
 collection.SetInherited(false)
-
 ~~~
 
-- Register and remove SEO
-
+### Register models to SEO
 ~~~go
 // Register mutiple SEO by name
-collection.RegisterSEOByNames("Not Found", "Internal Server Error")
+collection.RegisterSEOByNames("Product", "Announcement")
 
 // Register a SEO by model
 type Product struct{
@@ -57,47 +31,73 @@ type Product struct{
 	Setting Setting
 }
 collection.RegisterSEO(&Product{})
+~~~
 
-// Remove a SEO
-collection.RemoveSEO(&Product{}).RemoveSEO("Not Found")
+### Remove models from SEO
+~~~
+// Remove by struct
+collection.RemoveSEO(&Product{})
+// Remove by name
+collection.RemoveSEO("Not Found")
 ~~~
 
-- Configure SEO
+## Configuration
 
+### Change the default SEO name
 ~~~go
-// Change the default SEO name when register a SEO by model
-
 collection.RegisterSEO(&Product{}).SetName("My Product")
+~~~
 
-// Register a context Variable
+### Register customized variables
+~~~go
 collection.RegisterSEO(&Product{}).
-			RegisterContextVariables("og:image", func(obj interface{}, _ *Setting, _ *http.Request) string {
-						return obj.image.url
-					}).
-			RegisterContextVariables("Name", func(obj interface{}, _ *Setting, _ *http.Request) string {
-						return obj.Name
-					})
-
+	RegisterContextVariables("og:image", func(obj interface{}, _ *Setting, _ *http.Request) string {
+		// this will render "og:image" with the value of the object in the current request
+		return obj.image.url
+	}).
+	RegisterContextVariables("Name", func(obj interface{}, _ *Setting, _ *http.Request) string {
+		return obj.Name
+	})
+~~~
 
-// Register setting variable
-collection.RegisterSEO(&Product{}).
-			RegisterSettingVaribles(struct{ProductTag string}{})
+### Register setting variable
+~~~go
+collection.RegisterSEO(&Product{}).RegisterSettingVaribles(struct{ProductTag string}{})
 ~~~
 
-- Render SEO html data
+### Render SEO html data
 
 ~~~go
 // Render Global SEO
 collection.RenderGlobal(request)
 
-// Render SEO by a name
+// Render SEO by name
 collection.Render("product", request)
 
-// Render SEO by a model
+// Render SEO by model
 collection.Render(Product{}, request)
 ~~~
 
+## Customization
 `),
+	Markdown(`
+You can customize your SEO settings by implementing the interface and adding functions such as l10n and publish.`),
+	ch.Code(generated.QorSEOSettingInterface).Language("go"),
+
 	htmlgo.H2("Example"),
 	ch.Code(generated.SeoExample).Language("go"),
+
+	Markdown(`
+## Definition
+~~Collection~~ manages all the registered models and hold global seo settings.`),
+	ch.Code(generated.SeoCollectionDefinition).Language("go"),
+
+	Markdown(`
+~~SEO~~ provides system-level default page matadata.`),
+	ch.Code(generated.SeoDefinition).Language("go"),
+
+	Markdown(`
+You can use seo setting at the model level, but you need to register the model to the system SEO`),
+	ch.Code(generated.SeoModelExample).Language("go"),
+	ch.Code(`collection.RegisterSEO(&Product{})`).Language("go"),
 ).Title("SEO")