From 4aa3051a2917759ac40d51f274ea40404a6034ff Mon Sep 17 00:00:00 2001 From: James J Balamuta Date: Wed, 6 Dec 2023 20:27:08 -0800 Subject: [PATCH] Re-organize the website and update the README file --- README.md | 31 ++++++++++-- docs/_quarto.yml | 3 ++ docs/index.qmd | 69 ++------------------------ docs/qgads-ad-global-configuration.qmd | 39 +++++++++++++++ docs/qgads-installation.qmd | 31 ++++++++++++ 5 files changed, 104 insertions(+), 69 deletions(-) create mode 100644 docs/qgads-ad-global-configuration.qmd create mode 100644 docs/qgads-installation.qmd diff --git a/README.md b/README.md index 188493e..21baa33 100644 --- 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 index 9a74dc8..539d330 100644 --- 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 index 7d9c1e1..39668f6 100644 --- 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 new file mode 100644 index 0000000..5066b1a --- /dev/null +++ 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 new file mode 100644 index 0000000..88417f1 --- /dev/null +++ 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! \ No newline at end of file