Demo

HTML to improve our product and tell stories more effectively

What are HTML files good for?

The entire internet is run on the back of HTML, which is a coding language designed to be displayed in a web browser. HTML files are small and enable researchers to create interactive graphics to enhance the reader’s understanding of complex topics.

Drawbacks of relying solely on static graphics (the status quo):

• Difficult to add details without making the image too dense.

• Limited space, especially as graphs get more datapoints.
  

• GIFs are valuable for posting on social media, but clunky and frustrating in an article in a website.

• So many columns! Wouldn’t it be nice to be able to interact with each one?

• Not very helpful to readers to just get the names of obscure outposts in the South China Sea with no historical context. Could move a lot of routine background info from written updates into clickable pop-ups in the map.

How do HTML files add extra functionality?

They allow us to create interactive elements!

Graphs:

This is an interactive scatter plot on Taiwanese legislators undergoing recall elections, where each point is labelled with name and district. This example highlights the following benefits:

• Context: Readers who want to find particular districts/legislators don’t have to dig through electoral data themselves to further investigate the info presented in this chart.

• Numerical labels: Hover text eliminates the need to compromise on numerical accuracy to avoid cluttering the graph. It’s a cleaner look.

• Reader engagement: Likely will also enhance user interaction and improve information retention. Readers are likely to spend more time playing with the data in an interactive graph compared to a static image.

• Transformative analysis: We are able to present data in a more meaningful way through these methods, which enhances the depth of analysis readers take away from our work. This can improve ISW’s reputation and value.

There are dozens of interactive graph options available that more effectively condense information compared to default options in Microsoft Excel. See more here: https://r-graph-gallery.com/interactive-charts.html

Interactive Image Sliders

Instead of relying on GIFs to compare before/after imagery, we can embed a small bit of HTML that allows readers to investigate at their own pace. This uses a small HTML script that displays these two images interactively. (These images are stored in imgur, which we might want a better solution for. They have to be stored somewhere, but maybe our website has a way to upload assets that can be called by embedded HTML?)

Drag the slider to compare imagery of Fordow

ArcGIS Interactive Maps

ArcGIS Maps, which the GEOINT team uses every single day, are actually best displayed embedded in website using HTML! Previously, if we wanted to include a map we were constrained to either static maps or linking to an interactive map run through an ArcGIS storymap page. Our most popular two are the Ukraine Interactive map and Syria interactive map. At these links, you will notice the URL is actually an ESRI website, which means the reader is now stuck outside our site.

Instead of using these ArcGIS pages we can embed these maps directly in our website, keeping traffic on our page and enhancing written work with interactive maps right there as a part of the story, not as a link to a separate page.

For example, we have included maps showing dollars spent by oblast as a part of the force generation update.

Instead, we could embed an interactive map below the body text, like so. You can pan and click around!

Or like this! This loads faster but doesn’t interact with the pop-ups as well as the previous map.

Beyond ArcGIS, interactive graphics can also be constructed in R.

Taiwanese legislative recalls could have potentially had geographic patterns, so mapping out the datapoints and color-coding them is valuable. Taiwan’s population is heavily concentrated along the coast so it is very difficult to evenly space out the icons for legislative seats.

Contrast the interactive version with this static version.

The map above shows the maximum dot size possible to represent each legislative seat, and the color coding is indiscernible at that size.

The interactive map not only allows readers to zoom in on densely-populated areas to examine districts in detail, but it also provides a lot of additional information via hover-text: geographic labels, numerical values from the color-coding scale, etc.

China team is also planning to create an interactive network where readers can explore connections between purged members of the People’s Liberation Army and understand how they are connected in the command-structure.

This type of product loses a lot of value in static form. It is a forthcoming research product that will be used for internal reference at minimum, but it would be a shame if we couldn’t publish it due to website constraints.

Sample method to create network charts: https://r-graph-gallery.com/network-interactive.html

↑ Return to Top

Implementing HTML Logistics:

This is a reference website on the feature this proposal seeks permission to use: Custom HTML block - Wordpress.com Support

Steps to use the Custom HTML block:

1. Upload the HTML file into some online hosting software.
   • You are reading this page right now through the powers of GitHub, which is a free platform that hosts open source projects. GitHub has unlimited storage for public projects. A potential drawback to consider is that the HTML code we host on GitHub and our account history is available to the public. All of the data and coding methods we use is open-source anyways, so the only concern here is from an organizational standpoint on allowing the public to access code from ISW researchers. This point is reiterated in the Licensing section.
2. Use the HTML code block feature in WordPress to embed it into the website.
   • Karina has successfully used the code block on the AEI website and it takes about a minute to embed after one is familiar with how to do it.
   • Embed code:

<iframe class="mobile-hide" src="URL GOES HERE" width="100%" height="776"></iframe>

• It takes approximately 5 minutes to walk someone new through the process and is extremely easy to troubleshoot.

Note: Complex projects such as the interactive map (2000 lines of code) are too much for the WordPress built-in HTML code editor to handle. It crashes the website. This is why we need GitHub – need to get an external site to host the code so the ISW site simply calls on the URL.

Karina created an interactive map integrated with the China Team update in the way described above via the AEI WordPress account to demonstrate what she hopes to do on ISW’s website: China-Taiwan Weekly Update, July 24, 2025 American Enterprise Institute - AEI

Unique advantages afforded through the GitHub/WordPress method:

1. Quick and easy to train ER staff to use. The researcher will handle the HTML file hosting, so ER would only need to plug in the URL from the researcher into the code block provided above.
2. Free and no new installations. GitHub is free and we already have the WordPress HTML code editor feature on our new site.
3. Displays interactive features without having to open a new tab. This is unlike our current ArcGIS maps. Otherwise, most readers probably aren’t going to bother clicking.
4. Low website resource usage. HTML files aren’t particularly complicated and they load quickly. It’s faster than booting up the ArcGIS interactive maps.

Proposed usage frequency:

• Monthly at minimum for China team ADIZ incursion updates. Karina plans to convert this graph into an interactive style that displays more nicely. This would also open the door to more creative visualizations as we are currently severely constrained by our website capabilities. Taiwanese legislative recalls are still ongoing and there may be further room for analysis with interactive maps. China team is also looking to publish an interactive network of purged PLA officials in the coming months.
• GEOINT would use these features monthly at a minimum, and would mostly use it to supplement less-frequent publications like the occupation update, as opposed to the daily Russian update. As more staff are trained and more ideas are developed, the frequency could increase.

Next Steps:

• Gain approval to host HTML code on the new ISW site.
• Gain approval to continue using GitHub to host HTML code.
• Understand what the options for displaying on mobile are - either through Wordpress or in a one-script-fits-all approach. How does ER approach structuring the website for web/mobile?
• Gain permission to test how much HTML code the ISW website can handle before crashing.
• Upgrade existing routine graphics to take advantage of interactive capabilities.
• Begin brainstorming new graphics and train staff or interns on these newfound capabilities.

Licensing details:

R and Rstudio (used by Karina):

This software is distributed under the terms of the GNU General Public License, either Version 2, June 1991 or Version 3, June 2007. The terms of version 2 of the license are in a file called COPYING which you should have received with this software and which can be displayed by RShowDoc(“COPYING”). Version 3 of the license can be displayed by RShowDoc(“GPL-3”).

Copies of both versions 2 and 3 of the license can be found at https://www.R-project.org/Licenses/.

A small number of files (the API header files listed in R_DOC_DIR/COPYRIGHTS) are distributed under the LESSER GNU GENERAL PUBLIC LICENSE, version 2.1 or later. This can be displayed by RShowDoc(“LGPL-2.1”), or obtained at the URI given. Version 3 of the license can be displayed by RShowDoc(“LGPL-3”).

‘Share and Enjoy.’

GitHub

GitHub is free for organizations, and comes with:

• Deployment protection rules for public repositories
• Two-factor authentication enforcement
• 500 MB GitHub Packages storage
• 120 GitHub Codespaces core hours per month
• 15 GB GitHub Codespaces storage per month
• GitHub Actions features:
  • Deployment protection rules for public repositories
  • GitHub Pages in public repositories
• Team access controls for managing groups

GitHub repositories (folders where code is stored) can be private, which would prevent anyone stealing Karina’s cool graphs (or the data behind them). Depending on how we are going to deploy HTML to the website, some code might have to be public so that it is visible to others. This is something we can solve as we test the best use practices with the website.

↑ Return to Top