Re-organize the website and update the README file

coatless-quarto · Dec 7, 2023 · 4aa3051 · 4aa3051
1 parent b0be639
commit 4aa3051
Show file tree

Hide file tree

Showing 5 changed files with 104 additions and 69 deletions.
diff --git a/README.md b/README.md
@@ -22,7 +22,16 @@ This command will download and install the extension under the `_extensions` sub
 
 ## Usage
 
-Open either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) Project file and add the following:
+There are two modes available for the extension: 
+
+1. A global configuration that allows a consistent option to be set for multiple pages with an option to opt a page out.
+2. A localized single page configuration.
+
+**Note:** Ads may take up to an hour to appear on the page/project.
+
+### Multi-page Projects: Websites and Books
+
+If you have a website or book, you can use either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) files to avoid needing to consistently set the value. Add into the configuration file: 
 
 ```yml
 adsense:
@@ -34,15 +43,29 @@ filters:
 
 where `ca-pub-XXXXXXXXXXXXXXXX` in `publisher-id` is your Google Adsense [Publisher ID](https://support.google.com/adsense/answer/105516?hl=en).
 
-
-Ads may be disabled on a specific page by adding to the generating document's YAML header area:
+If you wish to disable ads on a specific page, then add to the Quarto document's YAML header area:
 
 ```yml
 adsense:
   enable-ads: false
 ```
 
-**Note:** Ads may take up to an hour to appear on the page/project.
+For more information, please see Quarto's documentation on [Shared Metadata](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata).
+
+### Single Page Projects: HTML Document
+
+If you only have one HTML document, we recommend setting up the extension by placing the required fields into the document's header section, e.g.
+
+```yml
+---
+title: "Demo Setup"
+author: "FirstName LastName"
+adsense:
+  publisher-id: ca-pub-XXXXXXXXXXXXXXXX
+filters:
+- adsense
+---
+```
 
 ## References
 

diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -15,8 +15,11 @@ website:
     contents: 
       - text: "Home"
         file: index.qmd
+      - text: "Installation"
+        file: qgads-installation.qmd
       - section: "Demos"
         contents:
+        - qgads-ad-global-configuration.qmd
         - qgads-ad-localized-page.qmd
         - qgads-ad-free-page.qmd
       - section: "Support"

diff --git a/docs/index.qmd b/docs/index.qmd
@@ -1,72 +1,11 @@
 ---
 title: "Home"
-adsense:
-  publisher-id: ca-pub-XXXXXXXXXXXXXXXX
-filters:
-- adsense
 ---
 
-The `adsense` extension allows you to incorporate [Google Adsense](https://adsense.google.com/start/) ad's on various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [Websites](https://quarto.org/docs/websites/), and [Books](https://quarto.org/docs/books). 
+The `adsense` extension allows you to incorporate [Google Adsense](https://adsense.google.com/start/) ad's on various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [Websites](https://quarto.org/docs/websites/), and [Books](https://quarto.org/docs/books). This extension is required as [Quarto does **not** natively support Google Adsense](https://github.com/quarto-dev/quarto-cli/discussions/2898#discussioncomment-3905621), but [does have support for Google Analytics](https://quarto.org/docs/websites/website-tools.html#google-analytics).
 
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/coatless-quarto/adsense)
-
-This extension is required as [Quarto does **not** natively support Google Adsense](https://github.com/quarto-dev/quarto-cli/discussions/2898#discussioncomment-3905621), but [does have support for Google Analytics](https://quarto.org/docs/websites/website-tools.html#google-analytics).
-
-## Installation
-
-To install the `adsense` extension, follow these steps:
-
-1. Open your terminal.
-
-2. Execute the following command:
-
-```bash
-quarto add coatless-quarto/adsense
-```
-
-This command will download and install the extension under the `_extensions` subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.
-
-## Usage
-
-There are two ways you can setup the extension: 1. in a separate configuration file (`_quarto.yml` or `_metadata.yml`) or 2. inside a document's header.
-
-### Multi-page Projects: Websites
-
-If you have a website or book, you can use either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) files to avoid needing to consistently set the value. This means, you would only need to include:
-
-```yml
-adsense:
-  publisher-id: ca-pub-XXXXXXXXXXXXXXXX
-
-filters:
-- adsense
-```
-
-If you wish to disable ads on a specific page, then add to the document's YAML header area:
-
-```yml
-adsense:
-  enable-ads: false
-```
-
-For more information, please see Quarto's documentation on [Shared Metadata](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata).
-
-### Single Page Projects: HTML Document
-
-If you only have one HTML document, we recommend setting up the extension by placing the required fields into the document's header section, e.g.
-
-```yml
----
-title: "Demo Setup"
-author: "FirstName LastName"
-adsense:
-  publisher-id: ca-pub-XXXXXXXXXXXXXXXX
-filters:
-- adsense
----
-```
-
-## Disclaimer
+Ready to get started? Check out the [installation steps](qgads-installation.qmd) and the preferred [setup approach using a global configuration](qgads-ad-global-configuration.qmd). 
 
+:::{.callout-important}
 This Quarto extension is open source software and is **not affiliated with** Google. The extension is at best a community effort to simplify the integration of Google's Adsense product inside of Quarto websites.
-
+:::
diff --git a/docs/qgads-ad-global-configuration.qmd b/docs/qgads-ad-global-configuration.qmd
@@ -0,0 +1,39 @@
+---
+title: "Global Adsense Configuration for Multi-page Projects"
+---
+
+## Overview
+
+This example demonstrates how to globally enable ads across all webpages by specifying options in either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) files. This allows you to avoid the need for repetitive configurations by centralizing the setup. 
+
+## Global Configuration
+
+To globally set Adsense parameters for your project, insert the following snippet into the chosen metadata file ([`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata)):
+
+```yaml
+adsense:
+  publisher-id: ca-pub-XXXXXXXXXXXXXXXX
+  filters:
+    - adsense
+```
+
+This configuration ensures that the specified Google Adsense publisher ID is applied consistently across all pages within your project.
+
+To find your Google Adsense publisher ID, please see Google's [Find your Publisher ID](https://support.google.com/adsense/answer/105516?hl=en) documentation.
+
+## Page-specific Configuration
+
+If you need to disable ads on a specific page, you can easily do so by adding the following YAML code to the header area of the document:
+
+```yaml
+adsense:
+  enable-ads: false
+```
+
+This local configuration takes precedence over the global settings, allowing for fine-grained control on a per-page basis.
+
+For more detailed insights into shared metadata and global configurations, refer to Quarto's documentation on [Shared Metadata](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata).
+
+## Result
+
+Ads should now be served across all pages or a directory of pages on your Quarto website.
diff --git a/docs/qgads-installation.qmd b/docs/qgads-installation.qmd
@@ -0,0 +1,31 @@
+---
+title: "Installation Guide for Quarto Adsense Extension"
+---
+
+## Installation
+
+To seamlessly integrate the `adsense` extension into your Quarto project, follow these straightforward steps:
+
+1. **Open Your Terminal:**
+   Open your terminal or command prompt.
+
+2. **Execute the Installation Command:**
+   Run the following command to automatically download and install the extension:
+
+   ```bash
+   quarto add coatless-quarto/adsense
+   ```
+
+   This command installs the `adsense` extension in the `_extensions` subdirectory of your Quarto project. If you're utilizing version control, make sure to include this directory in your repository.
+
+## Usage
+
+You can configure the `adsense` extension in either of the following ways:
+
+1. [Global Configuration Using a Configuration File](qgads-ad-localized-page.qmd):
+   Set up the extension globally by incorporating the relevant configuration in either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) file. This ensures consistent usage across all documents in your project.
+
+2. [Document-specific Configuration in YAML Header](qgads-ad-global-configuration.qmd):
+   Customize the extension settings for individual documents by adding configuration details to the YAML header of the respective Quarto document. This approach allows for fine-tuned control on a per-document basis.
+
+Select the configuration method that best suits your project's needs to learn more!